# What JSON Structure Is Used for Archify Architecture Diagrams?

> Explore the specific JSON structure required for Archify architecture diagrams. Learn about the essential schema_version, diagram_type, meta, and components fields.

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

---

**Archify architecture diagrams rely on a strict JSON schema defined in [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) that requires the top-level fields `schema_version`, `diagram_type`, `meta`, and `components`, while optionally accepting `layout`, `boundaries`, `connections`, and `cards` to define grid placement, visual groupings, and component relationships.**

The tt-a1i/archify repository implements a schema-driven validation system where understanding the specific **JSON structure used for Archify architecture diagrams** is essential for generating valid visualizations. This formal schema, located at [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json), enforces strict typing on diagram metadata, component definitions, and spatial relationships to ensure predictable rendering across environments.

## Root Schema Requirements

At the root level, the JSON structure must include four mandatory fields:

- **`schema_version`**: Integer value fixed at `1`
- **`diagram_type`**: String set to `"architecture"`
- **`meta`**: Object containing human-readable diagram information
- **`components`**: Array of diagram elements (servers, databases, frontend services, etc.)

Optional root-level collections include `layout` for grid-based positioning, `boundaries` for visual groupings like security groups, `connections` for linking components, and `cards` for reusable UI elements.

## Metadata Configuration

The `meta` object requires a `title` field and supports additional descriptive properties:

- **`title`** (required): String describing the diagram
- **`subtitle`**: Optional secondary description
- **`output`**: Optional output path or format configuration
- **`animation`**: Enum string, either `"trace"` or `"none"`
- **`viewBox`**: Array specifying canvas dimensions as `[width, height]` with a minimum size of 320 × 240 pixels

## Grid Layout System

When `mode` is set to `"grid"`, the optional `layout` object controls component placement with the following properties:

- **`mode`**: Must be `"grid"`
- **`cols`**: Number of grid columns
- **`gapX`** and **`gapY`**: Horizontal and vertical spacing between cells
- **`cellW`** and **`cellH`**: Individual cell width and height
- **`origin`**: Optional `[x, y]` point defining the grid origin

## Component Definitions

Each item in the `components` array represents a visual element with strict identification requirements.

Required fields for every component:

- **`id`**: Unique identifier referenced by `boundaries` and `connections`
- **`type`**: Component category (e.g., `"frontend"`, `"database"`, `"cache"`)
- **`label`**: Display text rendered on the diagram

Optional component fields include:

- **`sublabel`**: Secondary text displayed below the primary label
- **`tag`**: Classification or grouping tag
- **`row`** and **`col`**: Grid coordinates when using layout mode
- **`pos`**: Explicit `[x, y]` point coordinates for absolute positioning
- **`size`**: Dimensions specified as `[width, height]`

## Visual Boundaries

The `boundaries` array defines logical groupings such as AWS regions or security zones. Each boundary object requires:

- **`kind`**: Either `"region"` or `"security-group"`
- **`label`**: Boundary display name
- **`wraps`**: Array of component `id`s to visually enclose
- **`pad`**: Optional padding value around the grouped components

## Connection Specifications

Connections link components through the `connections` array with detailed routing controls:

- **`from`** and **`to`**: Component `id`s specifying start and end points
- **`label`**: Text description of the connection
- **`variant`**: Styling variant identifier
- **`fromSide`** and **`toSide`**: Attachment sides on source and target components
- **`route`**: Routing algorithm specification
- **`via`**: Array of `[x, y]` points defining custom path routing
- **`labelAt`**, **`labelDx`**, **`labelDy`**: Precise label positioning controls
- **`labelSegment`**: Which path segment carries the label
- **`width`**: Line thickness in pixels

## Schema References and Shared Definitions

All identifier formats, point definitions, and base types are pulled from the shared **[`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json)** via JSON Schema `$ref` references. This centralized approach ensures that component `id` validation, coordinate systems, and other fundamental types remain consistent across all diagram types in the Archify ecosystem.

## Practical Example

The following JSON demonstrates a valid architecture diagram configuration using grid layout:

```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
    },
    {
      "id": "api",
      "type": "backend",
      "label": "API Gateway",
      "col": 1,
      "row": 0
    }
  ]
}

```

## Summary

- **Archify architecture diagrams** require a specific JSON structure defined in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) with mandatory fields `schema_version` (set to `1`), `diagram_type` (set to `"architecture"`), `meta`, and `components`.
- The `meta` object requires a `title` string and optionally accepts `subtitle`, `output`, `animation` settings (`"trace"` or `"none"`), and `viewBox` dimensions with a minimum of 320×240 pixels.
- Components must define `id`, `type`, and `label`, with optional positioning via `row`/`col` indices when using grid layout or absolute coordinates via the `pos` array.
- Optional `boundaries` create visual groupings using `kind` values of `"region"` or `"security-group"`, enclosing components listed in the `wraps` array.
- Connections support complex routing through `via` point arrays, side attachments (`fromSide`, `toSide`), and detailed label positioning parameters.
- Type consistency is maintained through references to [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) for all identifier and point definitions.

## Frequently Asked Questions

### What is the minimum required JSON structure for an Archify architecture diagram?

The minimum valid structure must include four top-level fields: `schema_version` set to the integer `1`, `diagram_type` set to the string `"architecture"`, a `meta` object containing at least a `title` string, and a `components` array with at least one object defining `id`, `type`, and `label` properties. Omitting any of these required fields will cause validation errors against the [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) schema.

### How does Archify handle component positioning in the JSON structure?

Archify supports two positioning strategies within the **JSON structure used for Archify architecture diagrams**: grid-based placement using the optional `layout` object with `mode: "grid"` combined with component `row` and `col` indices, or absolute positioning using the `pos` array property containing `[x, y]` coordinates. The layout approach also allows configuring `gapX`, `gapY`, `cellW`, and `cellH` to control spacing and cell dimensions.

### What are boundaries and how are they defined in the schema?

Boundaries are optional visual groupings defined in the `boundaries` array that logically enclose related components, such as AWS regions or security groups. Each boundary requires a `kind` property (either `"region"` or `"security-group"`), a `label` for display purposes, and a `wraps` array listing the component `id`s to be enclosed, with optional `pad` values for spacing adjustments.

### Where are the base type definitions stored for Archify schemas?

Archify centralizes base type definitions—including identifiers, points, and common structures—in [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json), which the architecture schema references via JSON Schema `$ref` pointers. This shared approach ensures that component `id` formats, coordinate systems, and other fundamental types remain consistent across all diagram types in the tt-a1i/archify repository.