# Archify Schema Structure for Each Diagram Type: Complete JSON Reference

> Explore Archify's JSON schema structure for Architecture, Data Flow, Workflow, Sequence, and Lifecycle diagrams. Understand diagram metadata and type-specific fields for efficient technical documentation.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: api-reference
- Published: 2026-08-06

---

**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]` |

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json)  
**Example:** [`archify/examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/common.schema.json))

### Minimal Architecture Example

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json)  
**Example:** [`archify/examples/product-analytics.dataflow.json`](https://github.com/tt-a1i/archify/blob/main/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

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json)  
**Example:** [`archify/examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/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

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json)  
**Example:** [`archify/examples/cache-miss-request.sequence.json`](https://github.com/tt-a1i/archify/blob/main/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

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json)  
**Example:** [`archify/examples/agent-run.lifecycle.json`](https://github.com/tt-a1i/archify/blob/main/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

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) | `components`, `boundaries` | `layout` object |
| Data Flow | [`dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/dataflow.schema.json) | `stages`, `flows` | `stage` index on nodes |
| Workflow | [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json) | `lanes`, `edges` | `columns` + `col` positioning |
| Sequence | [`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/sequence.schema.json) | `participants`, `activations` | Implicit by participant order |
| Lifecycle | [`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json), [`dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/dataflow.schema.json), [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json), [`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/sequence.schema.json), and [`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json). They reference shared definitions from [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) for the `meta` block, views, legends, and cards.