Archify Schema Structure for Each Diagram Type: Complete JSON Reference

Archify defines five distinct JSON schemas—Architecture, Data Flow, Workflow, Sequence, and Lifecycle—each sharing a common "meta" block for diagram metadata while adding type-specific fields for elements like components, nodes, participants, or states.

Every diagram in Archify is validated against a strict JSON schema that ensures consistent rendering and interoperability. The schemas are located in archify/schemas/ and enforce both shared conventions and diagram-type-specific structures. Below is the complete breakdown of each schema, including required fields, type-specific sections, and minimal working examples.

Shared Meta Block Across All Diagram Types

All five schemas include a mandatory meta object that describes the diagram's presentation and context. According to the Archify source code, this block controls everything from animation settings to repository linking.

Meta Block Fields

Field	Type	Description
title	string (min 1)	Required diagram title
subtitle	string	Optional subtitle
output	string	Output format specification
animation	enum	"trace" or "none"
visual_preset	enum	"classic", "signal-flow", "blueprint", "editorial"
quality_profile	enum	"standard" or "showcase"
engineering_profile	enum	"deployment-ownership"
repository	object	url and 40-character revision SHA
views	$ref	Guided views from common.schema.json#/$defs/guidedViews
legend	object	mode and entries configuration
viewBox	array	[width ≥ 320, height ≥ 240]

{
  "meta": {
    "title": "System Architecture",
    "subtitle": "Production deployment",
    "output": "svg",
    "animation": "trace",
    "visual_preset": "blueprint",
    "quality_profile": "showcase",
    "repository": {
      "url": "https://github.com/org/repo",
      "revision": "a1b2c3d4e5f6789012345678901234567890abcd"
    },
    "viewBox": [1280, 720]
  }
}

Architecture Diagram Schema Structure

File: archify/schemas/architecture.schema.json
Example: archify/examples/web-app.architecture.json

Required Top-Level Fields

• schema_version (integer)
• diagram_type (must be "architecture")
• meta (object)
• components (array)

Type-Specific Sections

layout — Grid configuration controlling visual arrangement:

• mode: layout algorithm
• origin: optional coordinate origin
• cols, gapX, gapY: column count and spacing
• cellW, cellH: cell dimensions

components — Array of system elements, each requiring:

• id, type, label
• Optional: sublabel, tag, sources, row, col, pos, size

boundaries — Optional grouping constructs:

• kind: "region" or "security-group"
• label, wraps (component ID list), optional pad

connections — Optional relationship links:

• from, to (component IDs)
• Optional: label, variant, side/route hints, styling

cards — Optional guided-view cards (referenced from common.schema.json)

Minimal Architecture Example

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { "title": "Simple Web Stack" },
  "components": [
    { "id": "browser", "type": "frontend", "label": "Browser" },
    { "id": "cdn", "type": "cloud", "label": "CDN" }
  ],
  "connections": [
    { "from": "browser", "to": "cdn", "label": "HTTPS", "variant": "emphasis" }
  ]
}

Data Flow Diagram Schema Structure

File: archify/schemas/dataflow.schema.json
Example: archify/examples/product-analytics.dataflow.json

Required Top-Level Fields

• schema_version, diagram_type ("dataflow"), meta
• stages, nodes, flows

Type-Specific Sections

stages — Pipeline phases, each requiring only label

nodes — Processing units with:

• Required: id, type, label, stage, row
• Optional: size, sublabel, tag, yOffset

flows — Data movements between nodes:

• Required: from, to, label
• Optional: classification, variant, route hints, channel coordinates, label offsets, width

cards — Optional guided views

Minimal Data Flow Example

{
  "schema_version": 1,
  "diagram_type": "dataflow",
  "meta": { "title": "Analytics Pipeline" },
  "stages": [{ "label": "Ingest" }, { "label": "Store" }],
  "nodes": [
    { "id": "sdk", "type": "frontend", "label": "SDK", "stage": 0, "row": 0 },
    { "id": "db", "type": "database", "label": "DB", "stage": 1, "row": 0 }
  ],
  "flows": [
    { "from": "sdk", "to": "db", "label": "event", "variant": "emphasis" }
  ]
}

Workflow Diagram Schema Structure

File: archify/schemas/workflow.schema.json
Example: archify/examples/agent-tool-call.workflow.json

Required Top-Level Fields

• schema_version, diagram_type ("workflow"), meta
• lanes, columns, nodes, edges

Type-Specific Sections

lanes — Swim lanes for organizational grouping:

• Required: id, label
• Optional: sublabel, tag, positioning data

columns — Integer count for grid-style horizontal layout

nodes — Task/step definitions:

• Required: id, type, label, lane, col
• Optional: row, size, pos

edges — Control flow between nodes:

• from, to with optional label, variant, routing info

cards — Optional guided views

Minimal Workflow Example

{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { "title": "Agent Tool-Call" },
  "lanes": [
    { "id": "ui", "label": "User Interface" },
    { "id": "agent", "label": "Agent Runtime" }
  ],
  "columns": 4,
  "nodes": [
    { "id": "request", "type": "task", "label": "User Request", "lane": "ui", "col": 0 },
    { "id": "plan", "type": "task", "label": "Planner", "lane": "agent", "col": 1 }
  ],
  "edges": [
    { "from": "request", "to": "plan", "label": "asks", "variant": "emphasis" }
  ]
}

Sequence Diagram Schema Structure

File: archify/schemas/sequence.schema.json
Example: archify/examples/cache-miss-request.sequence.json

Required Top-Level Fields

• schema_version, diagram_type ("sequence"), meta
• participants, messages, activations

Type-Specific Sections

participants — Actors in the sequence:

• Required: id, type, label
• Optional: row, pos

messages — Interactions between participants:

• Required: from, to, label
• Optional: variant, routing data

activations — Optional lifecycle spans showing active periods for participants

cards — Optional guided views

Minimal Sequence Example

{
  "schema_version": 1,
  "diagram_type": "sequence",
  "meta": { "title": "Cache-Miss Request" },
  "participants": [
    { "id": "browser", "type": "frontend", "label": "Browser" },
    { "id": "api", "type": "backend", "label": "API" }
  ],
  "messages": [
    { "from": "browser", "to": "api", "label": "GET /", "variant": "emphasis" }
  ]
}

Lifecycle Diagram Schema Structure

File: archify/schemas/lifecycle.schema.json
Example: archify/examples/agent-run.lifecycle.json

Required Top-Level Fields

• schema_version, diagram_type ("lifecycle"), meta
• lanes, states, transitions

Type-Specific Sections

lanes — State machine phases (main, interrupts, recovery, terminal):

• Required: id, label

states — Individual state definitions:

• Required: id, label, lane, col
• Optional: row, size, pos

transitions — Valid state movements:

• Required: from, to, label
• Optional: variant, routing hints, width

cards — Optional guided views

Minimal Lifecycle Example

{
  "schema_version": 1,
  "diagram_type": "lifecycle",
  "meta": { "title": "Job Lifecycle" },
  "lanes": [
    { "id": "main", "label": "Main Phase" }
  ],
  "states": [
    { "id": "queued", "label": "Queued", "lane": "main", "col": 0, "row": 0 },
    { "id": "running", "label": "Running", "lane": "main", "col": 1, "row": 0 }
  ],
  "transitions": [
    { "from": "queued", "to": "running", "label": "start" }
  ]
}

Schema Validation Quick Reference

Diagram Type	Schema Location	Key Unique Field	Grid Control
Architecture	architecture.schema.json	components, boundaries	layout object
Data Flow	dataflow.schema.json	stages, flows	stage index on nodes
Workflow	workflow.schema.json	lanes, edges	columns + col positioning
Sequence	sequence.schema.json	participants, activations	Implicit by participant order
Lifecycle	lifecycle.schema.json	states, transitions	lanes + col/row grid

Summary

• All five diagram types share the same meta block structure for titles, styling, animation, and repository linking
• Architecture diagrams use components and connections with flexible grid layout configuration
• Data Flow diagrams organize processing through stages, nodes, and labeled flows
• Workflow diagrams employ lanes and columns for swim-lane task orchestration
• Sequence diagrams focus on participants exchanging messages with optional activations
• Lifecycle diagrams model state machines via states and transitions within phase lanes
• Optional cards are available across all types for guided-view annotations

Frequently Asked Questions

What is the minimum required JSON to create a valid Archify diagram?

Every diagram requires schema_version, diagram_type, meta (with at least title), and the type-specific element array—components for Architecture, nodes/flows/stages for Data Flow, nodes/edges/lanes for Workflow, participants/messages for Sequence, or states/transitions/lanes for Lifecycle. The examples above show the smallest valid documents for each type.

How does the meta block differ between diagram types?

It doesn't differ—the meta block is identical across all five schemas, loaded from common.schema.json references. This ensures consistent handling of titles, subtitles, visual presets, quality profiles, repository links, guided views, legends, and viewBox dimensions regardless of diagram type.

Can I use the same id values across different element types?

No—IDs must be unique within their containing array (components, nodes, participants, states, etc.) but can repeat across different arrays. For example, a node ID "api" in Data Flow won't conflict with a component ID "api" in Architecture, but two nodes with the same ID in one Data Flow diagram will fail validation.

Where are the schema files located in the repository?

All schemas reside in archify/schemas/: architecture.schema.json, dataflow.schema.json, workflow.schema.json, sequence.schema.json, and lifecycle.schema.json. They reference shared definitions from common.schema.json for the meta block, views, legends, and cards.

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