How to Write Valid JSON for the Archify Architecture Diagram Schema

To write valid JSON for the Archify architecture diagram schema, your document must include the mandatory top-level fields schema_version (set to 1), diagram_type (set to "architecture"), a meta object containing at least a title, and a non-empty components array where each element specifies id, type, label, pos, and size properties.

The tt-a1i/archify repository validates every diagram against a strict JSON Schema defined in archify/schemas/architecture.schema.json. This schema enforces type safety, required properties, and structural relationships to ensure diagrams render correctly. Understanding the exact field requirements prevents validation errors when using the Archify CLI or programmatic APIs.

Mandatory Top-Level Fields

Every architecture diagram JSON must contain four top-level keys as defined in the schema's required array.

• schema_version: Must be the integer 1. This constant guarantees compatibility with the current schema iteration.
• diagram_type: Must be the string "architecture". This distinguishes architecture diagrams from other diagram types like workflow or dataflow.
• meta: An object containing human-readable metadata. At minimum, it must include a title string.
• components: A non-empty array of Component Objects. Each object represents a node in your diagram, such as a service, database, or external system.

Omitting any of these fields or providing incorrect types will result in immediate schema validation failures.

Configuring the Meta Object

The meta object controls how Archify renders and labels your diagram. Beyond the required title, you can specify several optional properties defined in architecture.schema.json:

• subtitle: A short description displayed beneath the title.
• output: Filename for the generated HTML or PNG output.
• animation: Entry animation style; accepts "trace" or "none".
• visual_preset: Rendering theme; options include "classic", "signal-flow", "blueprint", or "editorial".
• quality_profile: Rendering fidelity; choose "standard" or "showcase".
• engineering_profile: Currently only supports "deployment-ownership".
• repository: An object linking to source code with url (GitHub URL) and revision (40-character SHA).
• viewBox: A two-item numeric array [width, height] defining the canvas size. The schema enforces minimum values of 320 for width and 240 for height.

Defining Components

The components array is where you declare every visual node. The schema validates each component against definitions imported from common.schema.json and local constraints. Each component requires:

• id: A unique string identifier referenced by connections and boundaries.
• type: A predefined category such as frontend, backend, database, cloud, security, messagebus, or external.
• label: A non-empty string displayed on the diagram node.
• pos: A coordinate pair [x, y] defining absolute positioning. This is required unless you use grid-based layout.
• size: A numeric pair [width, height] where both values must be greater than 0.

Optional component fields include sublabel and tag for additional labeling, sources for code references (file path and line numbers), and row/col indices for grid placement.

Optional Layout and Positioning

You have two mutually exclusive strategies for component positioning.

Absolute Positioning: Provide pos arrays directly in each component object. This offers pixel-perfect control but requires manual coordinate management.

Grid Layout: Supply a top-level layout object with mode set to "grid". When using grid mode, components use row and col properties instead of pos. The layout object accepts optional geometry controls:

• origin: Starting coordinates [x, y].
• cols: Number of columns.
• gapX, gapY: Spacing between cells.
• cellW, cellH: Cell dimensions.

If you omit the layout object entirely, Archify defaults to absolute positioning and requires pos in every component.

Visual Relationships: Boundaries and Connections

To group components or draw arrows between them, use the optional boundaries and connections arrays.

Boundaries create visual groupings like regions or security zones. Each boundary object requires:

• kind: Either "region" or "security-group".
• label: Display text for the boundary.
• wraps: An array of component id strings to enclose.
• pad (optional): Padding in pixels.

Connections define directed edges between components. Required fields are from and to, both referencing component ids. Optional connection properties include:

• label and variant for styling (e.g., "emphasis", "security", "dashed").
• fromSide and toSide for anchor points ("left", "right", "top", "bottom").
• route for path calculation ("auto", "straight", "orthogonal-h", "orthogonal-v").
• via for manual routing through intermediate points.
• width for line thickness (minimum 0.5).

Validating Your JSON

Archify provides a CLI validation command to check your document against architecture.schema.json before rendering.

# Using the Archify CLI

archify validate my-diagram.json

# Using ajv-cli (Node.js)

npm install -g ajv-cli
ajv validate -s archify/schemas/architecture.schema.json -d my-diagram.json

Validation errors reference specific schema violations, such as missing required fields or type mismatches in components.

Complete JSON Examples

Minimal Valid Diagram

This example satisfies all mandatory requirements without optional fields:

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Minimal Service"
  },
  "components": [
    {
      "id": "api",
      "type": "backend",
      "label": "API Server",
      "pos": [100, 100],
      "size": [120, 60]
    }
  ]
}

Full-Featured Production Example

For a complete implementation demonstrating boundaries, connections, and advanced meta options, reference the official example in archify/examples/web-app.architecture.json:

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Sample Web App",
    "subtitle": "Classic 3-tier SaaS on AWS",
    "output": "web-app-rendered.html",
    "quality_profile": "showcase",
    "visual_preset": "classic",
    "viewBox": [800, 600]
  },
  "components": [
    {
      "id": "cdn",
      "type": "cloud",
      "label": "CloudFront",
      "pos": [200, 100],
      "size": [140, 70]
    },
    {
      "id": "api",
      "type": "backend",
      "label": "API Gateway",
      "pos": [400, 100],
      "size": [140, 70]
    }
  ],
  "boundaries": [
    {
      "kind": "region",
      "label": "AWS Region",
      "wraps": ["cdn", "api"]
    }
  ],
  "connections": [
    {
      "from": "cdn",
      "to": "api",
      "label": "HTTPS",
      "variant": "emphasis"
    }
  ]
}

Summary

• Four mandatory top-level fields: schema_version (1), diagram_type ("architecture"), meta (with title), and components (non-empty array).
• Component requirements: Each node needs id, type, label, pos (unless using grid), and size (both dimensions > 0).
• Positioning modes: Use absolute pos coordinates or define a layout object with mode: "grid" and row/col indices.
• Relationships: Add boundaries to group components visually and connections to draw arrows with optional routing hints.
• Validation: Run archify validate <file> or use ajv against architecture.schema.json to catch schema violations early.

Frequently Asked Questions

What are the mandatory fields for an Archify architecture diagram?

Your JSON must include schema_version set to 1, diagram_type set to "architecture", a meta object containing at least a title string, and a components array with at least one element. Each component must have id, type, label, pos, and size properties according to the schema defined in architecture.schema.json.

How do I position components without using a grid layout?

Omit the top-level layout object and provide a pos array [x, y] inside each component object. The pos coordinates use absolute pixel positioning within the canvas defined by meta.viewBox. This approach gives you direct control over node placement without grid constraints.

What component types are supported in the schema?

The schema defines specific allowed values for the type property including frontend, backend, database, cloud, security, messagebus, and external. These types determine the visual iconography and styling applied to each node in the rendered diagram.

How can I validate my Archify JSON before rendering?

Use the Archify CLI command archify validate <filename> to check your document against the official schema. Alternatively, use any JSON Schema validator like ajv or Python's jsonschema library, pointing to archify/schemas/architecture.schema.json and archify/schemas/common.schema.json for complete type definitions.

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