Archify JSON IR Schema Structure: A Complete Guide to Diagram Syntax

The Archify JSON IR schema structure uses a typed Intermediate Representation with a mandatory schema_version and diagram_type, containing lanes, nodes, edges, and optional summaryCards that are validated against versioned JSON Schema definitions.

Every diagram in Archify (tt-a1i/archify) compiles to a typed JSON IR (Intermediate Representation)—a structure that separates semantic content from visual rendering. This article breaks down the exact schema structure validated by the AJV-powered pipeline, based on the source definitions in archify/schemas/.

---

Core Schema Properties Common to All Diagram Types

All diagram types extend a shared base schema located at archify/schemas/common.schema.json. The top-level object requires these fields:

Property	Type	Required	Description
schema_version	integer	Yes	Schema version: 1 for architecture/dataflow/sequence, 2 for modern workflow diagrams
diagram_type	string	Yes	Renderer selection: workflow, architecture, dataflow, sequence, or lifecycle
nodes	array	Yes	Visual elements with unique IDs, placement hints, and type-specific styling
lanes	array	No	Lane containers for workflow/sequence/lifecycle diagrams
edges	array	No	Connections between nodes with routing and styling variants
summaryCards	array	No	Floating explanatory cards with positioning metadata
metadata	object	No	Tool-specific key-value pairs (generator, timestamp, etc.)

Validation uses AJV with JSON Schema draft-2020-12. Failures abort rendering and report the exact JSON Pointer path.

---

Node Schema Structure

The nodes array is the universal building block. Each node object supports these fields according to archify/schemas/common.schema.json:

• id (string, required): Unique identifier referenced by edges
• type (string, required): Visual primitive—process, decision, messagebus, start, end
• label (string): Primary display text
• sublabel (string): Secondary descriptive text
• lane (string): Lane assignment for lane-based diagrams
• row / col (number): Grid positioning
• pos ([number, number]): Absolute [x, y] coordinates for free-form placement
• width / height / size (number): Dimension overrides
• tag (string): Color-coding identifier (workflow-specific, e.g., "structured result")

---

Edge Schema Structure

Edges in the edges array define relationships with these properties:

• from / to (string, required): Source and target node IDs
• label (string): Optional edge annotation
• variant (string): Visual style—emphasis, security, warning, muted
• route (string): Routing algorithm hint—straight, curved, orthogonal
• fromSide / toSide (string): Attachment side—top, right, bottom, left

The security variant triggers special "policy-gate" visual treatment in workflow renderers.

---

Diagram-Specific Schema Extensions

Workflow Schema (workflow.schema.json)

Located at archify/schemas/workflow.schema.json, this schema (version 2) adds lane-based layout:

• lanes entries require unique id and support direction (horizontal | vertical)
• messagebus nodes accept a tag field for color coding
• edges support the security variant for approval gates

Architecture Schema (architecture.schema.json)

Defined in archify/schemas/architecture.schema.json:

• No lanes; uses free-form pos coordinates or row/col grid
• Hierarchical relationships via optional parent/children fields
• Emphasizes spatial positioning over sequential flow

Dataflow Schema (dataflow.schema.json)

In archify/schemas/dataflow.schema.json:

• Nodes typically use type: "messagebus" for stream semantics
• stage field (number): Denotes processing pipeline position
• Edges carry streaming semantics with partition awareness

Sequence Schema (sequence.schema.json)

Per archify/schemas/sequence.schema.json:

• lanes represent participants/lifelines
• Specialized message types for sync/async communication
• Activation bars and return messages as edge variants

---

Complete JSON IR Examples

Workflow Diagram (Schema v2)

{
  "schema_version": 2,
  "diagram_type": "workflow",
  "lanes": [
    { "id": "ui",        "label": "User Interface" },
    { "id": "planner",   "label": "Planner" },
    { "id": "approval",  "label": "Approval Gate" },
    { "id": "tool",      "label": "Tool Execution" }
  ],
  "nodes": [
    { "id": "request", "lane": "ui",      "col": 0, "type": "process", "label": "User Request" },
    { "id": "plan",    "lane": "planner", "col": 1, "type": "process", "label": "Plan" },
    { "id": "gate",    "lane": "approval","col": 2, "type": "decision","label": "Needs Approval?" },
    { "id": "tool",    "lane": "tool",    "col": 3, "type": "messagebus","label": "Tool Call", "tag": "structured result" }
  ],
  "edges": [
    { "from": "request", "to": "plan",    "variant": "emphasis" },
    { "from": "plan",    "to": "gate",    "variant": "emphasis" },
    { "from": "gate",    "to": "tool",    "variant": "security", "label": "approved" }
  ],
  "summaryCards": [
    {
      "title": "Approval Gate",
      "body": "Human‑in‑the‑loop checkpoint before invoking external tools.",
      "row": 1,
      "col": 2
    }
  ]
}

Architecture Diagram (Schema v1)

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "nodes": [
    { "id": "frontend", "type": "process", "label": "Frontend", "pos": [100,200] },
    { "id": "api",      "type": "process", "label": "API Server", "pos": [300,200] },
    { "id": "db",       "type": "messagebus", "label": "PostgreSQL", "pos": [500,200] }
  ],
  "edges": [
    { "from": "frontend", "to": "api", "variant": "emphasis" },
    { "from": "api",      "to": "db",  "variant": "emphasis" }
  ]
}

Dataflow Diagram (Schema v1)

{
  "schema_version": 1,
  "diagram_type": "dataflow",
  "nodes": [
    { "id": "orders",   "type": "messagebus", "label": "orders.v1",   "sublabel": "12 partitions", "stage": 1, "row": 0 },
    { "id": "payments", "type": "messagebus", "label": "payments.v2", "sublabel": "8 partitions",  "stage": 1, "row": 2 },
    { "id": "dlq",      "type": "messagebus", "label": "events.dlq",  "sublabel": "poison events", "stage": 3, "row": 4 }
  ],
  "edges": [
    { "from": "orders",   "to": "payments", "variant": "emphasis", "label": "OrderPlaced" },
    { "from": "payments", "to": "dlq",      "variant": "warning",  "label": "Failed" }
  ]
}

---

Schema Validation Behavior

The Archify pipeline validates JSON IR at two stages:

1. Parse-time validation: AJV checks against the appropriate schema file in archify/schemas/
2. Render-time validation: The target diagram renderer verifies semantic constraints (e.g., all edge from/to IDs exist in nodes)

Validation errors include the exact JSON Pointer path (e.g., /nodes/2/label) and abort processing before SVG/PNG generation.

---

Key Source Files

File	Purpose
archify/schemas/common.schema.json	Base schema with universal nodes, edges, metadata definitions
archify/schemas/workflow.schema.json	Lane-based workflow diagrams with schema_version: 2
archify/schemas/architecture.schema.json	Free-form spatial diagrams with coordinate positioning
archify/schemas/dataflow.schema.json	Streaming dataflow with stage and messagebus semantics
archify/schemas/sequence.schema.json	Sequence diagrams with participant lifelines
archify/test/fixtures/	Example JSON IR files for regression testing

---

Summary

• Archify JSON IR uses a typed, versioned structure with mandatory schema_version and diagram_type fields
• Common base schema (common.schema.json) defines nodes, edges, lanes, summaryCards, and metadata available to all diagram types
• Schema extensions add diagram-specific fields: workflow uses direction and tag; dataflow uses stage; architecture uses pos coordinates
• Validation runs via AJV (draft-2020-12) with precise error reporting via JSON Pointer paths
• Test fixtures in archify/test/fixtures/ provide working examples of each schema variant

---

Frequently Asked Questions

What is the current schema version for Archify workflow diagrams?

Workflow diagrams use schema_version: 2 as defined in archify/schemas/workflow.schema.json. Other diagram types (architecture, dataflow, sequence) currently use schema_version: 1. The version determines which renderer branch processes the IR and which validation rules apply.

Can I mix schema versions within a single diagram file?

No. Each JSON IR document has exactly one schema_version at the root level. The version selects the base validation schema and renderer pipeline. To use newer workflow features, migrate the entire document to version 2.

What happens if my JSON IR fails schema validation?

AJV validation aborts the rendering pipeline and returns an error with the exact JSON Pointer path to the offending property (e.g., /edges/0/from references a missing node). The CLI exits with a non-zero status and detailed validation output; no output image is generated.

How do I add custom metadata to a diagram without breaking validation?

Include arbitrary key-value pairs in the metadata object at the root level. This field is defined in common.schema.json as an unconstrained object and is ignored by renderers but preserved for downstream tooling.

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