# Archify JSON Intermediate Representation (IR): Schema-Validated Diagram Rendering

> Discover the Archify JSON Intermediate Representation IR a versioned schema validated data structure enabling deterministic SVG generation through strict validation before layout calculations.

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

---

**The Archify JSON Intermediate Representation is a versioned, schema-validated data structure that serves as the canonical contract between diagram authors and the rendering engine, enabling deterministic SVG generation through strict validation before layout calculations.**

The Archify JSON Intermediate Representation (IR) is the central data format powering the tt-a1i/archify diagram rendering pipeline. Unlike traditional tools that parse raw text directly into graphics, Archify first converts diagrams into a structured JSON document that captures semantic relationships, layout metadata, and styling information. This intermediate layer creates a stable, version-controlled boundary between diagram logic and rendering implementation.

## What is the Archify JSON IR?

The JSON IR acts as a **stable contract** between diagram authors and Archify's rendering engine. Each IR document includes a `schema_version` field that guarantees backward compatibility—files validating today will render identically on future 2.x releases. When breaking changes occur, the version bumps and older files receive clear validation errors rather than silent rendering failures.

## Six Critical Purposes of the JSON IR

### Schema Validation Before Rendering

Before any layout work begins, Archify validates incoming JSON against strict typed schemas. The system uses AJV (Another JSON Schema Validator) through `archify/renderers/shared/validator.mjs` to check against diagram-specific schemas: [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json), [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json), [`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json), [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json), or [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json). This prevents unknown fields from silently corrupting output and eliminates runtime npm or network dependencies by shipping a generated validator with the skill.

### Version-Stable Rendering

The `schema_version` field in every IR document ensures **deterministic rendering** across releases. When the Archify team introduces breaking schema changes, they increment the version number and reject outdated documents with explicit error messages. This policy, documented in [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md), guarantees that archived diagrams remain visually stable years after creation.

### Diff-Friendly Editing

Because the IR consists of plain JSON objects, version control systems display changes as precise `git diff` hunks. Modifying a node's coordinates, swapping themes, or adjusting edge labels produces isolated, readable diffs. Claude (the LLM) can perform **incremental edits** to the IR without regenerating entire diagrams, preventing visual drift between iterations.

### Separation of Concerns

The IR cleanly isolates **semantic information** (nodes, edges, lanes, phases) from **rendering concerns** (SVG path generation, CSS animations, layout heuristics). Renderers consume the validated IR, perform geometry calculations, and output HTML/SVG. This architecture makes renderers focused, testable units that don't need to parse raw diagram syntax.

### Extensible Architecture

New diagram types integrate by defining a new schema in `archify/schemas/` and implementing a matching renderer. Because all renderers share the validation pipeline in `archify/renderers/shared/validator.mjs`, the system maintains consistency as it grows. Each new diagram type automatically inherits schema validation and version checking.

### Performance Optimization

Validation occurs before expensive layout calculations begin. The standalone AJV validators process quickly, rejecting malformed input early in the pipeline. This prevents wasted computational effort on geometry calculations for invalid diagrams.

## JSON Schema Structure and File Locations

Archify maintains separate JSON Schema files for each diagram type in the `archify/schemas/` directory:

- [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json): Defines lanes, phases, nodes, and edges for workflow diagrams
- [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json): Handles sequence diagram lifelines and messages
- [`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json): Manages dataflow diagram components and data streams
- [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json): Covers state machine transitions and states
- [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json): Defines architecture diagram elements and relationships

The [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md) documents the versioning policy and schema evolution rules.

## Workflow Example: Creating and Rendering the JSON IR

Below is a minimal workflow IR that satisfies [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json). Save this as [`my-workflow.json`](https://github.com/tt-a1i/archify/blob/main/my-workflow.json):

```json
{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": {
    "title": "Sample Order Workflow"
  },
  "lanes": [
    { "id": "frontend", "label": "Frontend" },
    { "id": "backend", "label": "Backend" }
  ],
  "phases": [
    { "id": "order", "label": "Order", "lane": "frontend" },
    { "id": "process", "label": "Process", "lane": "backend" }
  ],
  "nodes": [
    { "id": "ui", "label": "UI", "phase": "order" },
    { "id": "api", "label": "API", "phase": "process" }
  ],
  "edges": [
    { "source": "ui", "target": "api", "label": "Submit Order" }
  ]
}

```

Render the diagram using the CLI entry point at `archify/bin/archify.mjs`:

```bash
node archify/bin/archify.mjs render workflow my-workflow.json > diagram.html

```

The CLI execution follows this pipeline:

1. Loads [`my-workflow.json`](https://github.com/tt-a1i/archify/blob/main/my-workflow.json) from disk
2. Validates the structure against [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) using the AJV validator in `archify/renderers/shared/validator.mjs`
3. Passes the verified IR to `archify/renderers/workflow/render-workflow.mjs`
4. Generates a self-contained HTML file with embedded SVG and optional CSS animations

## Renderer Implementation and IR Consumption

Renderers do not handle raw parsing or validation logic. The `render-workflow.mjs` module receives a validated JavaScript object containing the IR data and focuses exclusively on geometry calculations and SVG generation. This design allows renderers to assume input correctness, eliminating defensive coding patterns and reducing complexity.

The validator guarantees that required fields like `schema_version`, `diagram_type`, `nodes`, and `edges` exist and contain valid types before the renderer executes. This contract enables renderers to access properties directly without null checks for schema-level validation failures.

## Summary

- The Archify JSON Intermediate Representation provides a **versioned, schema-validated contract** between diagram authors and the rendering engine.
- **AJV validation** occurs in `archify/renderers/shared/validator.mjs` before any layout calculations, rejecting malformed input early.
- The `schema_version` field ensures **deterministic rendering** across releases, with breaking changes triggering explicit version bumps.
- Plain JSON structure enables **diff-friendly editing** and incremental modifications by Claude or human authors.
- **Separation of concerns** isolates semantic data (nodes, edges) from rendering logic (SVG generation), making components testable.
- New diagram types extend the system by adding schemas to `archify/schemas/` and implementing targeted renderers.

## Frequently Asked Questions

### What is the Archify JSON Intermediate Representation?

The Archify JSON Intermediate Representation is a structured data format that captures the semantic graph and layout metadata of diagrams before rendering. Located in the tt-a1i/archify repository, it serves as a canonical intermediate layer between raw diagram descriptions and final SVG/HTML output. The IR uses JSON Schema validation to ensure structural correctness and version compatibility.

### How does schema versioning work in Archify?

Every IR document includes a `schema_version` integer that locks the file to a specific schema revision. According to [`archify/schemas/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/README.md), valid files continue rendering identically across all future 2.x releases. When maintainers introduce breaking changes, they increment the schema version and update the validator, causing older files to fail validation with clear error messages rather than rendering incorrectly.

### Why does Archify validate JSON before rendering?

Validation occurs in `archify/renderers/shared/validator.mjs` using pre-compiled AJV validators to catch schema violations before expensive layout calculations begin. This early rejection prevents wasted CPU cycles on geometry calculations for malformed diagrams and eliminates silent failures from unknown fields. The approach also removes runtime npm dependencies since validators ship with the skill.

### Can I manually edit the Archify JSON IR?

Yes, the JSON IR supports manual editing because it uses plain JSON objects that produce readable `git diff` output. Claude and human authors can modify specific properties—such as node coordinates, edge labels, or theme settings—without regenerating the entire diagram structure. Changes validate against the appropriate schema (e.g., [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json)) before rendering, ensuring manual edits maintain structural integrity.