# Archify Architecture Diagram JSON Schema Structure: Complete Reference Guide

> Explore the Archify architecture diagram JSON schema structure in this comprehensive guide. Understand the required and optional properties for effective diagram definition.

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

---

**The Archify architecture diagram JSON schema is a strict, typed JSON IR defined in [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) that enforces `schema_version: 1`, `diagram_type: "architecture"`, and requires `meta` and `components` properties while optionally accepting `layout`, `boundaries`, `connections`, and `cards`.**

Archify renders SVG-based architecture diagrams from deterministic JSON documents. The **architecture diagram JSON schema** governs exactly how you structure these documents to ensure the renderer produces consistent, validated output. This guide walks through every top-level property, its constraints, and its role in the rendering pipeline based on the source code in `tt-a1i/archify`.

---

## Core Schema Requirements

Every valid architecture diagram must declare two fixed values at the root level. According to [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json), the top-level object requires:

| Property | Value | Purpose |
|----------|-------|---------|
| `schema_version` | `1` (integer, const) | Schema version lock for forward compatibility |
| `diagram_type` | `"architecture"` (string, const) | Discriminator for the multi-format renderer |

The schema sets `"additionalProperties": false`, rejecting any unrecognized keys. This guarantees that validated documents render identically across Archify versions.

---

## The `meta` Object: Diagram Metadata

The `meta` property (defined in [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) lines 11–66) captures all presentation and behavioral settings for the diagram.

### Required and Optional Fields

| Field | Required | Type/Values | Description |
|-------|----------|-------------|-------------|
| `title` | **yes** | non-empty string | Main heading displayed above the diagram |
| `subtitle` | no | string | Secondary descriptive line |
| `output` | no | string (path) | Target HTML file for rendered output |
| `animation` | no | `"trace"` \| `"none"` | SVG load animation style |
| `visual_preset` | no | `"classic"` \| `"signal-flow"` \| `"blueprint"` \| `"editorial"` | Pre-defined color palette and node shapes |
| `quality_profile` | no | `"standard"` \| `"showcase"` | Validation strictness and visual polish level |
| `engineering_profile` | no | `"deployment-ownership"` | Engineering-specific view modes |
| `repository` | no | `{url, revision}` object | Git commit linkage (GitHub URL pattern, 40-char SHA-1) |
| `views` | no | guided view array | Focused subsets of components (re-used from [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json)) |
| `legend` | no | `{mode, entries}` object | Legend visibility and custom labels |
| `viewBox` | no | `[width, height]` array (≥ 320×240) | Explicit SVG canvas dimensions |

The `legend.mode` accepts `"auto"`, `"compact"`, or `"hidden"` to control whether type labels appear below the diagram.

---

## The `layout` Object: Grid Placement Control

When you need deterministic positioning, the optional `layout` property configures an explicit grid system:

```json
{
  "layout": {
    "mode": "grid",
    "origin": [0, 0],
    "cols": 8,
    "gapX": 20,
    "gapY": 20,
    "cellW": 120,
    "cellH": 80
  }
}

```

| Property | Constraints | Default Behavior |
|----------|-------------|----------------|
| `mode` | `"grid"` only (required when layout present) | — |
| `origin` | `[x, y]` point array | Top-left grid corner |
| `cols` | integer 1–12 | Column count for component placement |
| `gapX`, `gapY` | non-negative numbers | Inter-cell spacing in pixels |
| `cellW` | minimum 40 | Minimum cell width |
| `cellH` | minimum 24 | Minimum cell height |

Omit `layout` entirely to let Archify's automatic layout engine compute positions based on connectivity and component types.

---

## The `components` Array: Diagram Nodes

The `components` array (lines 82–127 in [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json)) defines every node in your architecture. Each component is a strictly-shaped object:

```json
{
  "id": "api-gateway",
  "type": "backend",
  "label": "API Gateway",
  "sublabel": "v2.4.1",
  "tag": "nginx",
  "row": 1,
  "col": 3,
  "sources": [
    {"path": "src/gateway/main.go", "line": 1, "end_line": 150, "label": "entrypoint"}
  ]
}

```

### Component Properties

| Property | Required | Type/Constraints |
|----------|----------|----------------|
| `id` | **yes** | `/^[a-zA-Z][a-zA-Z0-9_-]*$/` — must start with letter |
| `type` | **yes** | `componentType` enum from [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json): `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, `external` |
| `label` | **yes** | non-empty display name |
| `sublabel` | no | secondary text below label |
| `tag` | no | arbitrary short string (often version) |
| `brand` | no | string (≤2048 chars) or `{url, sha256}` object for logo |
| `sources` | no | array of 0–3 source locations with `path`, optional `line`/`end_line`, optional `label` |
| `row`, `col` | no | zero-based grid coordinates |
| `pos` | no | `[x, y]` point overriding grid placement |
| `size` | no | `[width, height]` positive dimensions |

The `type` field drives visual styling—each `componentType` maps to distinct colors, icons, and node shapes in the renderer.

---

## The `boundaries` Array: Visual Grouping

**Boundaries** wrap components into logical regions or security zones. Defined in lines 128–145 of the schema:

```json
{
  "boundaries": [
    {
      "kind": "region",
      "label": "AWS us-east-1",
      "wraps": ["api-gateway", "auth-service", "user-db"],
      "pad": 16
    },
    {
      "kind": "security-group",
      "label": "DMZ",
      "wraps": ["api-gateway"]
    }
  ]
}

```

| Property | Required | Description |
|----------|----------|-------------|
| `kind` | **yes** | `"region"` (geographic/cloud grouping) or `"security-group"` (trust boundary) |
| `label` | **yes** | displayed inside the boundary rectangle |
| `wraps` | **yes** | array of component `id`s (minimum 1) |
| `pad` | no | extra padding in pixels around wrapped items |

Boundary `kind` determines stroke color and dash pattern—`"region"` uses solid lines while `"security-group"` applies security-themed styling.

---

## The `connections` Array: Directed Relationships

Edges link components with rich routing and styling control (lines 146–171):

```json
{
  "connections": [
    {
      "from": "api-gateway",
      "to": "auth-service",
      "label": "JWT verify",
      "variant": "security",
      "route": "orthogonal-h",
      "fromSide": "right",
      "toSide": "left",
      "width": 2.5
    }
  ]
}

```

### Edge Properties

| Property | Required | Type/Values |
|----------|----------|-------------|
| `from` | **yes** | source component `id` |
| `to` | **yes** | target component `id` |
| `id` | no | edge identifier (re-uses [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) `id` pattern) |
| `label` | no | text rendered along the edge |
| `variant` | no | `"default"` \| `"emphasis"` \| `"security"` \| `"dashed"` |
| `fromSide`, `toSide` | no | `"left"` \| `"right"` \| `"top"` \| `"bottom"` |
| `route` | no | `"auto"` \| `"straight"` \| `"orthogonal-h"` \| `"orthogonal-v"` |
| `via` | no | array of `{x, y}` points for forced bends |
| `width` | no | minimum 0.5 — SVG stroke width |

Label positioning accepts `labelAt` (0.0–1.0 along path), `labelDx`/`labelDy` (offset pixels), and `labelSegment` (which segment of multi-segment routes).

---

## The `cards` Array: Narrative Sidebars

Cards attach explanatory content beside the diagram, re-using definitions from [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json):

```json
{
  "cards": [
    {
      "dot": "emerald",
      "title": "Data Flow",
      "items": [
        "All requests flow through API Gateway",
        "Authentication enforced at edge",
        "Database connections use TLS 1.3"
      ]
    }
  ]
}

```

| Property | Required | Constraints |
|----------|----------|-------------|
| `dot` | **yes** | color: `cyan`, `emerald`, `violet`, `amber`, `rose`, `orange`, `slate` |
| `title` | **yes** | non-empty string |
| `items` | **yes** | array of bullet point strings |

Cards render as dismissible panels with colored bullets, useful for architectural decision records (ADRs), security notes, or operational runbooks.

---

## Complete Valid Example

This minimal architecture diagram validates against [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) and renders a three-tier web service:

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "E-Commerce Platform",
    "subtitle": "Production deployment",
    "visual_preset": "signal-flow",
    "legend": {"mode": "auto"},
    "viewBox": [800, 400]
  },
  "layout": {
    "mode": "grid",
    "cols": 6,
    "gapX": 24,
    "gapY": 32,
    "cellW": 140,
    "cellH": 100
  },
  "components": [
    {"id": "cdn", "type": "cloud", "label": "CloudFront", "col": 0, "row": 0},
    {"id": "web", "type": "frontend", "label": "Next.js", "col": 2, "row": 0},
    {"id": "api", "type": "backend", "label": "API", "col": 3, "row": 1},
    {"id": "cache", "type": "database", "label": "Redis", "col": 5, "row": 0},
    {"id": "postgres", "type": "database", "label": "PostgreSQL", "col": 5, "row": 1}
  ],
  "boundaries": [
    {"kind": "region", "label": "AWS", "wraps": ["cdn", "web", "api", "cache", "postgres"]}
  ],
  "connections": [
    {"from": "cdn", "to": "web", "route": "orthogonal-h"},
    {"from": "web", "to": "api", "variant": "emphasis"},
    {"from": "api", "to": "cache", "variant": "dashed"},
    {"from": "api", "to": "postgres", "variant": "security"}
  ],
  "cards": [
    {
      "dot": "cyan",
      "title": "Architecture Notes",
      "items": ["Read-heavy workload", "Cache-aside pattern", "Encrypted at rest"]
    }
  ]
}

```

For a production-scale reference, see [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) in the repository.

---

## Schema Validation and CI Integration

The Archify CLI uses AJV to validate documents against [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json). A typical CI pipeline:

1. **Lint** JSON syntax
2. **Validate** schema conformance: `archify validate diagram.architecture.json`
3. **Render** to HTML: `archify build diagram.architecture.json --output docs/`
4. **Assert** fixture parity: compare against [`archify/test/fixtures/v1-baseline/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/test/fixtures/v1-baseline/web-app.architecture.json)

Because the schema permits no extra properties and fixes version constants, validated diagrams produce byte-identical renders across Archify patch versions.

---

## Key Source Files

| Path | Purpose |
|------|---------|
| [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) | Master schema governing architecture diagrams |
| [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) | Shared `$ref` definitions: `id`, `point`, `componentType`, cards, legends |
| [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) | Full-featured example with all sections populated |
| [`archify/test/fixtures/v1-baseline/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/test/fixtures/v1-baseline/web-app.architecture.json) | CI regression test fixture |

---

## Summary

- **Archify architecture diagram JSON schema** requires `schema_version: 1`, `diagram_type: "architecture"`, and a `meta` object with at minimum a `title`
- **Components** are typed nodes (`frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, `external`) with mandatory `id` and `label`
- **Boundaries** group components by `kind: "region"` or `"security-group"` with mandatory `wraps` array
- **Connections** link `from` → `to` component IDs with optional routing, styling, and label positioning
- **Cards** attach narrative content with colored bullets alongside the rendered SVG
- Strict `additionalProperties: false` ensures schema conformance guarantees render reproducibility

---

## Frequently Asked Questions

### What happens if I omit the `layout` property?

Archify falls back to its automatic layout engine, computing positions based on connectivity patterns and component types. Grid coordinates in `components` are ignored when `layout` is absent.

### Can I reference external logo images in components?

Yes. The `brand` property accepts either a plain URL string (≤2048 characters) or an object with `url` and `sha256` for integrity verification: `{"url": "https://cdn.example.com/logo.svg", "sha256": "abc123..."}`.

### How do I link a diagram to a specific Git commit?

Use the `meta.repository` object with `url` matching GitHub's pattern and a 40-character `revision` SHA-1. This enables the renderer to generate permalinks and "view source" buttons in the output HTML.

### Why does schema validation reject my file with valid-looking JSON?

The [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) enforces `additionalProperties: false` at the root and on most nested objects. Typos in property names, extra fields, or incorrect types (e.g., string `"1"` instead of integer `1` for `schema_version`) will fail validation.