Archify JSON Schema Structure for Architecture Diagrams: Complete Reference

Archify defines architecture diagrams using a strict JSON schema called 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. 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 ids to enclose
• pad: Optional padding value

Connections draw lines between components using:

• from and to: Source and target component ids
• 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 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

{
  "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 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 in the tt-a1i/archify repository. This file defines all required fields, validation rules, and references to 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.

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