Archify JSON Intermediate Representation (IR) Schema Structure Explained

Archify's JSON Intermediate Representation (IR) is a strictly validated, schema-driven format that defines architecture, workflow, sequence, dataflow, and lifecycle diagrams as portable JSON documents.

The JSON IR schema serves as the core contract between diagram authors and Archify's rendering engine. Every diagram type follows a rigorous JSON Schema specification stored in archify/schemas/, ensuring type safety, validation, and interoperability across tools.

Core JSON IR Schema Structure

Top-Level Properties

All diagram IR documents share a common envelope structure defined in architecture.schema.json and sibling schema files:

Property	Type	Required	Description
schema_version	integer	Yes	Fixed value 1 for forward compatibility
diagram_type	string	Yes	One of: "architecture", "workflow", "sequence", "dataflow", "lifecycle"
meta	object	Yes	Metadata including title, subtitle, visual preset, and output configuration
layout	object	No	Grid or free-form positioning parameters
components / nodes	array	Varies	Diagram elements (terms differ by diagram type)
boundaries	array	No	Logical groupings that wrap component sets
connections / edges	array	No	Directed relationships between elements
cards	array	No	Supplementary annotations and legends

All top-level objects enforce additionalProperties: false, making validation failures explicit and catching typos immediately.

Architecture Diagram IR Schema

The architecture.schema.json file defines the most widely used IR format. Located at archify/schemas/architecture.schema.json, it structures diagrams as interconnected components within optional boundaries.

Components Array

Each element in components must satisfy:

{
  "id": "api-gateway",
  "type": "backend",
  "label": "API Gateway",
  "sublabel": "Nginx",
  "tag": "v2.1",
  "row": 0,
  "col": 1,
  "source_url": "https://github.com/org/repo",
  "source_path": "/src/gateway"
}

Component type values are drawn from the shared enum in common.schema.json:

• frontend
• backend
• database
• cloud
• security
• messagebus
• external

Boundaries for Logical Grouping

Boundaries wrap component references to create security groups or architectural layers:

{
  "boundaries": [
    {
      "kind": "security_group",
      "label": "DMZ",
      "wraps": ["api-gateway", "load-balancer"],
      "padding": 20
    }
  ]
}

Connections with Routing Control

The connections array supports automatic and manual routing:

{
  "from": "api-gateway",
  "to": "user-service",
  "variant": "emphasis",
  "route": "orthogonal",
  "via": [[200, 100], [400, 100]],
  "width": 2,
  "label": "HTTPS",
  "labelDx": 10,
  "labelDy": -5
}

Routing options include "auto", "direct", "orthogonal", and "curved". The via property accepts an array of [x, y] points for precise path control.

Shared Definitions in common.schema.json

The archify/schemas/common.schema.json file provides reusable schema fragments referenced by all diagram types:

Identifiers and Coordinates

• id: Regex pattern ^[a-zA-Z][a-zA-Z0-9_-]*$ for valid object identifiers
• point: Two-element numeric array [x, y] for positioning
• size: Object with width and height integers

Visual Styling Enums

The variant enum controls visual emphasis:

• default — standard appearance
• emphasis — highlighted (thicker borders, contrasting fill)
• security — specialized styling for security components
• dashed — indirect or optional relationships

Legends and Guided Views

{
  "legend": {
    "mode": "compact",
    "entries": [
      { "label": "External API", "type": "external" }
    ]
  },
  "guided_views": [
    {
      "id": "auth-flow",
      "label": "Authentication Flow",
      "center": [300, 200],
      "zoom": 1.5
    }
  ]
}

Workflow and Specialized Diagram IRs

Workflow IR Schema

Defined in archify/schemas/workflow.schema.json, workflow diagrams introduce lane-based layouts:

{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { "title": "CI/CD Pipeline" },
  "lanes": [
    { "id": "dev", "label": "Development" },
    { "id": "staging", "label": "Staging" },
    { "id": "prod", "label": "Production" }
  ],
  "phases": [
    { "id": "build", "label": "Build" },
    { "id": "test", "label": "Test" },
    { "id": "deploy", "label": "Deploy" }
  ],
  "nodes": [
    {
      "id": "compile",
      "lane": "dev",
      "col": 0,
      "type": "backend",
      "label": "Compile"
    }
  ],
  "edges": [
    {
      "from": "compile",
      "to": "unit-test",
      "role": "main"
    }
  ]
}

Workflow-specific properties:

• lanes — horizontal swimlanes for organizational grouping
• phases — vertical divisions for process stages
• groups — nested containment for complex workflows
• nodes — equivalent to components in architecture IR
• edges — equivalent to connections, with added role property

Sequence, Dataflow, and Lifecycle IRs

Each specialized diagram type has its own schema file following the same architectural pattern:

• sequence.schema.json — step-by-step interactions with steps array
• dataflow.schema.json — data transformation pipelines with stages
• lifecycle.schema.json — state transitions with states and transitions

All reference common.schema.json for identifiers, points, and component types.

Complete Architecture IR Example

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "E-Commerce Platform",
    "subtitle": "Reference Architecture",
    "visual_preset": "modern",
    "quality_profile": "high",
    "output_filename": "ecommerce-platform"
  },
  "layout": {
    "mode": "grid",
    "origin": [0, 0],
    "columns": 3,
    "gaps": [40, 60]
  },
  "components": [
    {
      "id": "cdn",
      "type": "cloud",
      "label": "CloudFront",
      "row": 0,
      "col": 0
    },
    {
      "id": "web",
      "type": "frontend",
      "label": "Next.js App",
      "row": 0,
      "col": 1,
      "sublabel": "SSR"
    },
    {
      "id": "api",
      "type": "backend",
      "label": "GraphQL API",
      "row": 0,
      "col": 2
    },
    {
      "id": "cache",
      "type": "database",
      "label": "Redis",
      "row": 1,
      "col": 2,
      "tag": "cluster"
    },
    {
      "id": "postgres",
      "type": "database",
      "label": "PostgreSQL",
      "row": 2,
      "col": 2
    }
  ],
  "boundaries": [
    {
      "kind": "security_group",
      "label": "Private Subnet",
      "wraps": ["cache", "postgres"],
      "padding": 30
    }
  ],
  "connections": [
    {
      "from": "cdn",
      "to": "web",
      "variant": "default",
      "route": "auto"
    },
    {
      "from": "web",
      "to": "api",
      "variant": "default",
      "route": "orthogonal"
    },
    {
      "from": "api",
      "to": "cache",
      "variant": "default",
      "route": "auto",
      "label": "session"
    },
    {
      "from": "api",
      "to": "postgres",
      "variant": "emphasis",
      "route": "auto",
      "label": "persistent"
    }
  ],
  "cards": [
    {
      "position": "top-right",
      "title": "Notes",
      "content": "Redis used for session store only"
    }
  ]
}

Validation and Tooling

The JSON IR schemas enable rigorous validation using standard JSON Schema validators like AJV. Key validation characteristics:

• Strict mode: additionalProperties: false on all objects
• Required fields: Enforced per diagram type and context
• Type coercion: Rejected — strings must be strings, numbers must be numbers
• Enum validation: Component types, variants, and routing modes checked against shared definitions

Validate an IR file against its schema:

ajv validate -s archify/schemas/architecture.schema.json -d diagram.architecture.json

Summary

• JSON IR is schema-validated: Every diagram type has a strict JSON Schema in archify/schemas/
• Shared definitions ensure consistency: common.schema.json provides single-source identifiers, points, and enums
• Architecture IR uses components and connections: Grid-based layout with optional boundaries
• Workflow IR adds lanes and phases: Swimlane layout for process visualization
• All IRs are portable and tool-agnostic: JSON format enables programmatic generation and third-party rendering

Frequently Asked Questions

What diagram types does Archify's JSON IR support?

Archify supports five diagram types, each with its own schema: architecture, workflow, sequence, dataflow, and lifecycle. The diagram_type field in each IR document identifies which schema governs validation.

Where are the JSON Schema files located?

All schemas reside in the archify/schemas/ directory. The core files are architecture.schema.json, workflow.schema.json, and common.schema.json. Additional schemas for sequence, dataflow, and lifecycle diagrams follow the same naming convention.

Can I extend the JSON IR with custom properties?

No — all schemas enforce additionalProperties: false to ensure strict validation. Custom data should be stored in the meta object's predefined fields or in cards annotations. This design guarantees that all valid IR documents render correctly across Archify versions.

How do I validate my JSON IR against the schema?

Use any JSON Schema validator such as AJV, or Archify's built-in validation. The schemas follow JSON Schema Draft 7 and can be invoked programmatically or via command-line tools to catch structural errors before rendering.

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