What JSON Structure Is Used for Archify Architecture Diagrams?

Archify architecture diagrams rely on a strict JSON schema defined in 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, 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 ids 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 ids 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 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:

{
  "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 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 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 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 ids 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, 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.

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