What JSON IR Schema Types Does Archify Support? A Complete Guide to All 5 Diagram Formats

Archify supports five distinct JSON IR schema types: Architecture, Workflow, Sequence, Data Flow, and Lifecycle—each validated by its own JSON Schema and identified by the required diagram_type field.

The tt-a1i/archify repository ingests JSON Intermediate Representation (IR) and deterministically compiles it into HTML/SVG diagrams. Before rendering, Archify validates every incoming payload against a dedicated schema based on the diagram_type specified. Understanding these five schema types is essential for generating valid diagram instructions programmatically.

---

Overview of the Five JSON IR Schema Types

Archify's validator selects the appropriate schema by inspecting the diagram_type string. Each type serves a distinct modeling purpose, from system architecture to state machines.

Diagram Type	Schema File	Purpose
Architecture	archify/schemas/architecture.schema.json	Component-based system maps with boundaries, connections, and cards
Workflow	archify/schemas/workflow.schema.json	CI/CD pipelines, approval processes, and procedural flows with lanes and nodes
Sequence	archify/schemas/sequence.schema.json	Ordered interactions between participants with messages and activations
Data Flow	archify/schemas/dataflow.schema.json	Data movement through stages, with classification and routing rules
Lifecycle	archify/schemas/lifecycle.schema.json	State machines including retries, waits, and terminal outcomes

All schemas require "schema_version": 1 and enforce type-specific constraints through JSON Schema validation.

---

The Architecture Schema Type

The Architecture schema models component-based systems. It supports services, databases, external systems, and the connections between them, organized within visual boundaries.

Key entities in architecture.schema.json:

• components — typed elements (service, database, external, queue, cache, etc.)
• boundaries — visual groupings with labels and containment lists
• connections — directed or bidirectional links between component IDs
• cards — additional informational boxes overlaying the diagram

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { "title": "Simple Service Architecture" },
  "components": [
    { "id": "svc", "type": "service", "label": "Service A" },
    { "id": "db", "type": "database", "label": "Primary DB" }
  ],
  "connections": [
    { "from": "svc", "to": "db", "label": "queries" }
  ]
}

Common component types include service, database, external, queue, cache, bucket, cdn, vpc, lambda, and user. The schema inherits shared definitions from common.schema.json for IDs, visual presets, and styling properties.

---

The Workflow Schema Type

The Workflow schema represents procedural flows using a lane-based layout. This JSON IR schema type excels at CI/CD pipelines, approval workflows, and any process with distinct phases or responsible parties.

Key entities in workflow.schema.json:

• lanes — horizontal swimlanes with IDs and display labels
• nodes — positioned elements within lanes (col index determines horizontal placement)
• edges — connections between nodes, supporting conditional routing

{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { "title": "CI Pipeline" },
  "lanes": [
    { "id": "build", "label": "Build" },
    { "id": "test", "label": "Test" }
  ],
  "nodes": [
    { "id": "compile", "lane": "build", "col": 0, "type": "task", "label": "Compile" },
    { "id": "unit", "lane": "test", "col": 0, "type": "task", "label": "Unit Tests" }
  ],
  "edges": [
    { "from": "compile", "to": "unit", "type": "sequence" }
  ]
}

Node types include task, decision, start, end, delay, and manual. The column-based positioning system ensures deterministic layout without manual coordinate specification.

---

The Sequence Schema Type

The Sequence schema captures ordered interactions between participants. This JSON IR schema type renders classic UML-style sequence diagrams with messages, activations, and optional segments.

Key entities in sequence.schema.json:

• participants — actors, services, or systems arranged left-to-right
• messages — directed communications with vertical positioning (y coordinate)
• activations — execution bars showing processing duration
• segments — optional labeled regions grouping related interactions

{
  "schema_version": 1,
  "diagram_type": "sequence",
  "meta": { "title": "API Call Sequence" },
  "participants": [
    { "id": "client", "type": "actor", "label": "Client" },
    { "id": "api", "type": "service", "label": "API Server" },
    { "id": "db", "type": "database", "label": "Database" }
  ],
  "messages": [
    { "from": "client", "to": "api", "y": 100, "label": "GET /resource" },
    { "from": "api", "to": "db", "y": 200, "label": "SELECT *" },
    { "from": "db", "to": "api", "y": 300, "label": "Result set" },
    { "from": "api", "to": "client", "y": 400, "label": "200 OK" }
  ]
}

Participant types inherit from common.schema.json and include actor, service, database, queue, and external. The explicit y coordinate system provides precise control over vertical spacing while maintaining readable left-to-right flow.

---

The Data Flow Schema Type

The Data Flow schema visualizes how information moves through processing stages. This JSON IR schema type supports ETL pipelines, data pipelines, and any system where data origin, transformation, and destination matter.

Key entities in dataflow.schema.json:

• stages — processing phases arranged left-to-right
• nodes — data sources, processors, and sinks positioned by stage and row
• flows — directed data movements with optional classification labels
• routing — conditional flow logic based on data properties

{
  "schema_version": 1,
  "diagram_type": "dataflow",
  "meta": { "title": "ETL Pipeline" },
  "stages": [
    { "label": "Extract" },
    { "label": "Transform" },
    { "label": "Load" }
  ],
  "nodes": [
    { "id": "src", "type": "source", "label": "Operational DB", "stage": 0, "row": 0 },
    { "id": "clean", "type": "process", "label": "Cleanse", "stage": 1, "row": 0 },
    { "id": "dst", "type": "sink", "label": "Data Warehouse", "stage": 2, "row": 0 }
  ],
  "flows": [
    { "from": "src", "to": "clean", "label": "Raw records" },
    { "from": "clean", "to": "dst", "label": "Clean records", "classification": "validated" }
  ]
}

Node types include source, sink, process, store, queue, and api. The stage/row positioning system creates clean pipeline visualizations without manual coordinate management.

---

The Lifecycle Schema Type

The Lifecycle schema describes state machines for services, jobs, or any entity with discrete states and transitions. This JSON IR schema type renders state diagrams with support for complex transition semantics.

Key entities in lifecycle.schema.json:

• states — named conditions with optional entry/exit behaviors
• transitions — directed state changes triggered by events
• retries — automatic re-entry logic for failed transitions
• waits — timed delays before transition availability
• terminal — final states that halt further processing

{
  "schema_version": 1,
  "diagram_type": "lifecycle",
  "meta": { "title": "Job Lifecycle" },
  "states": [
    { "id": "queued", "label": "Queued" },
    { "id": "running", "label": "Running", "entry": "allocate_resources" },
    { "id": "completed", "label": "Completed", "terminal": true },
    { "id": "failed", "label": "Failed", "terminal": true }
  ],
  "transitions": [
    { "from": "queued", "to": "running", "trigger": "dequeue" },
    { "from": "running", "to": "completed", "trigger": "success" },
    { "from": "running", "to": "failed", "trigger": "error" },
    { "from": "failed", "to": "queued", "trigger": "retry", "wait": 60, "max_retries": 3 }
  ]
}

The lifecycle schema uniquely supports orthogonal regions for modeling parallel state machines and compound states for hierarchical decomposition.

---

Shared Schema Infrastructure

All five JSON IR schema types reference archify/schemas/common.schema.json for consistent definitions:

• ID format — regex-constrained alphanumeric identifiers
• Component type enum — shared vocabulary across architecture, sequence, and data flow
• Visual presets — color schemes, icon references, and layout hints
• Meta structure — standard title, description, and authorship fields

This shared infrastructure ensures that tooling can process cross-cutting concerns—such as theming and accessibility—uniformly regardless of diagram type.

---

Schema Validation and Selection

When Archify receives JSON IR, it performs validation in two phases:

1. Type detection — extracts diagram_type and schema_version from the root object
2. Schema validation — loads the corresponding .schema.json file and validates against JSON Schema Draft 7

Validation failures include precise path references to help agents or users correct malformed IR. Valid payloads proceed to the compilation phase for deterministic HTML/SVG generation.

---

Summary

• Archify supports five JSON IR schema types: Architecture, Workflow, Sequence, Data Flow, and Lifecycle
• Each type has a dedicated schema file in archify/schemas/ and is identified by its diagram_type constant
• All schemas require schema_version: 1 and share common definitions from common.schema.json
• Architecture models component systems; Workflow handles procedural lanes and nodes
• Sequence captures ordered participant interactions; Data Flow traces information movement through stages
• Lifecycle represents state machines with retries, waits, and terminal conditions

---

Frequently Asked Questions

What happens if I omit the diagram_type field in my JSON IR?

Archify rejects the payload with a validation error. The diagram_type field is required in all schemas to determine which validator to apply. Without it, the system cannot select among architecture.schema.json, workflow.schema.json, or the other schema files.

Can I combine multiple diagram types in a single JSON IR file?

No. Each JSON IR document must specify exactly one diagram_type and conform to its corresponding schema. For multi-diagram outputs, generate separate IR files and invoke Archify multiple times, or use the architecture schema's nested boundary approach for high-level overviews.

Does Archify support schema versions beyond 1?

Currently all schemas enforce "schema_version": 1. The version field exists to enable future breaking changes. When new schema versions are introduced, Archify will maintain backward compatibility by selecting validators based on the version-determined schema path.

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