# Archify JSON Schema Structure for Architecture Diagrams: Complete Reference

> Explore the Archify JSON schema structure for architecture diagrams. Understand essential fields like schema_version, diagram_type, meta, and components for creating detailed visualizations.

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

---

**Archify defines architecture diagrams using a strict JSON schema called [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) that requires `schema_version`, `diagram_type`, `meta`, and `components` fields at the root level, with optional support for `layout`, `boundaries`, `connections`, and `cards`.**

The `tt-a1i/archify` repository implements a declarative diagram-as-code system where architecture diagrams are serialized as JSON documents. Understanding the **archify JSON schema structure** ensures your diagrams validate correctly and render properly in the visualization engine.

## Root Schema Requirements

Every architecture diagram must conform to the schema defined in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json). The root object requires four mandatory fields:

- **`schema_version`**: Currently fixed at integer `1`
- **`diagram_type`**: Must be the string `"architecture"`
- **`meta`**: Object containing human-readable metadata (see below)
- **`components`**: Array of diagram elements such as servers and databases

Optional top-level fields include `layout` for grid-based positioning, `boundaries` for visual groupings, `connections` for linking elements, and `cards` for reusable UI definitions.

## Meta Information Structure

The `meta` object stores display properties and export settings. According to the archify source code, this section requires a **`title`** string and accepts several optional fields:

- **`subtitle`**: Additional descriptive text
- **`output`**: Export configuration
- **`animation`**: Playback style using enumerated values `"trace"` or `"none"`
- **`viewBox`**: Array defining canvas dimensions as `[width, height]` with minimum values of `320` × `240`

## Layout Configuration

When `mode` is set to `"grid"`, the optional `layout` object controls automatic positioning:

- **`mode`**: Must be `"grid"`
- **`origin`**: Optional point defining the grid start position
- **`cols`**: Number of columns in the grid
- **`gapX`** and **`gapY`**: Horizontal and vertical spacing between cells
- **`cellW`** and **`cellH`**: Cell width and height dimensions

## Components Array

The `components` array contains the visual elements of your architecture. Each component object requires three fields:

- **`id`**: Unique identifier referenced by connections and boundaries
- **`type`**: Component classification (e.g., `"frontend"`, `"database"`)
- **`label`**: Display text for the element

Optional component properties include `sublabel` for secondary text, `tag` for categorization, grid coordinates (`row`, `col`), absolute positioning (`pos` as a point), and dimensions (`size` as `[width, height]`).

## Boundaries and Connections

**Boundaries** define visual groupings like security groups or regions. Each boundary specifies:
- **`kind`**: Either `"region"` or `"security-group"`
- **`label`**: Display name
- **`wraps`**: Array of component `id`s to enclose
- **`pad`**: Optional padding value

**Connections** draw lines between components using:
- **`from`** and **`to`**: Source and target component `id`s
- Optional routing controls: `variant`, `fromSide`, `toSide`, `route`
- **`via`**: Array of points for custom routing
- Label positioning: `labelAt`, `labelDx`, `labelDy`, `labelSegment`
- **`width`**: Line thickness

## Schema Dependencies

All identifiers, point definitions, and type enumerations are imported from **[`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json)** via JSON Schema `$ref` references. This ensures consistency across archify's various diagram types and prevents type mismatches between architecture diagrams and other supported visualizations.

## JSON Schema Example

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Sample Microservice Architecture",
    "subtitle": "v1.0",
    "animation": "trace"
  },
  "layout": {
    "mode": "grid",
    "cols": 6,
    "gapX": 20,
    "gapY": 20,
    "cellW": 80,
    "cellH": 50
  },
  "components": [
    {
      "id": "web",
      "type": "frontend",
      "label": "Web UI",
      "col": 0,
      "row": 0
    }
  ]
}

```

## Summary

- **Archify JSON schema structure** requires `schema_version: 1`, `diagram_type: "architecture"`, `meta`, and `components` at the root level
- The `meta` object mandates a `title` and supports `animation` modes of `"trace"` or `"none"`
- Components require `id`, `type`, and `label`, with optional grid positioning via `row`/`col` or absolute `pos` coordinates
- Boundaries group components using `kind` values of `"region"` or `"security-group"`
- Connections link components by `id` with extensive routing and labeling options
- Schema references [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) for shared type definitions and validation rules

## Frequently Asked Questions

### What file contains the official archify architecture schema?

The official schema resides at [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) in the `tt-a1i/archify` repository. This file defines all required fields, validation rules, and references to [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) for shared type definitions.

### Which fields are mandatory in the archify JSON schema?

The root object must include `schema_version` (integer `1`), `diagram_type` (string `"architecture"`), `meta` (object with required `title`), and `components` (array). All other fields including `layout`, `boundaries`, `connections`, and `cards` are optional.

### How does the grid layout system work in archify?

When `layout.mode` is set to `"grid"`, the system uses `cols`, `gapX`, `gapY`, `cellW`, and `cellH` to calculate positions. Components specify their grid location using `row` and `col` integers, or you can bypass the grid using absolute `pos` coordinates.

### Can I animate connections between components?

Yes, set `meta.animation` to `"trace"` for animated connection drawing, or `"none"` for static lines. This applies to all connections in the diagram as defined in the architecture schema.