# Archify Workflow Diagram Key Fields: Complete Schema Reference

> Explore the Archify workflow diagram schema reference and understand the seven mandatory JSON fields including schema version, diagram type, meta title, lanes, nodes, and edges.

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

---

**Archify workflow diagrams require seven mandatory JSON fields—`schema_version`, `diagram_type`, `meta.title`, `lanes`, `nodes`, and `edges`—plus optional configuration arrays for phases, groups, and semantic validation.**

Archify, the open-source diagram-as-code toolkit, encodes workflow diagrams as structured JSON-IR documents. According to the `tt-a1i/archify` source code, the schema enforces strict validation rules to ensure diagrams render consistently across the project's SVG, PNG, and interactive delivery pipelines.

## Mandatory Fields for Every Workflow Diagram

All workflow diagrams must satisfy the `required` array in [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) (lines 8‑14). Omitting any of these fields causes validation to fail.

| Field | Type | Purpose |
|-------|------|---------|
| `schema_version` | integer (`1` or `2`) | Schema compatibility version for migration tooling |
| `diagram_type` | string (fixed: `"workflow"`) | Discriminator for renderer dispatch |
| `meta` | object | Container for metadata; must include `title` |
| `meta.title` | string | Human-readable diagram name |
| `lanes` | array | Ordered vertical tracks that organize nodes |
| `nodes` | array | Individual process steps with positioning |
| `edges` | array | Directed connections between nodes |

A minimal valid document therefore contains these seven keys. The schema does not permit additional fields at the top level unless explicitly defined.

## Optional Meta Configuration Fields

The `meta` object (lines 36‑103) accepts renderer-specific settings that control output behavior without affecting diagram structure.

- **`locale`** – UI language code (e.g., `"en"`, `"de"`)
- **`subtitle`** – Secondary heading rendered beneath the title
- **`output`** – Custom filename for generated assets
- **`animation`** – SVG motion effect: `"trace"` for draw-on animation or `"none"` for static
- **`visual_preset`** – Predefined styling theme (e.g., `"classic"`, `"minimal"`)
- **`quality_profile`** – Export quality tier affecting DPI and compression
- **`views`** – Guided presentation modes for interactive viewers
- **`legend`** – Legend configuration for symbol decoding
- **`viewBox`** – Explicit SVG coordinate system override

## Structural Topology Arrays

Beyond metadata, Archify workflow diagrams describe visual layout through specialized arrays (lines 106‑401). These optional structures add semantic richness without violating the core schema contract.

### Lanes and Phases

**`lanes`** (lines 106‑132) define vertical swimlanes. Each lane requires `id` and `label`, with optional `variant` for styling overrides. **`phases`** (lines 134‑172) add horizontal bands spanning columns, using `fromCol` and `toCol` to establish boundaries.

### Groups and Main Path

**`groups`** (lines 173‑216) highlight rectangular regions for visual emphasis. **`mainPath`** (lines 217‑223) declares an ordered `["node1", "node2", ...]` sequence representing the primary workflow flow—used by renderers for animation choreography and accessibility labeling.

### Semantic Validation

**`semanticChecks`** (lines 224‑254) embed contract testing directly in the diagram definition:

- `allowedRoots` – Permitted starting node types
- `allowedTerminals` – Valid ending node types
- `requiredEdges` – Connections that must exist
- `requiredPaths` – Sequences that must be traversable

### Nodes, Edges, and Cards

**`nodes`** (lines 255‑309) position elements within the lane/column grid. Required per node: `id`, `lane`, `col`, `type`, `label`. Visual adjustments include `sublabel`, `tag`, `brand`, `width`, `height`, and `yOffset`.

**`edges`** (lines 310‑397) connect nodes via `from`/`to` references. Optional styling: `label`, `variant`, `role`, and routing hints for orthogonal pathfinding.

**`cards`** (lines 398‑401) render summary blocks below the main SVG—useful for executive dashboards or printed documentation.

## Minimal Valid Example

The following JSON satisfies all mandatory [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) requirements:

```json
{
  "schema_version": 2,
  "diagram_type": "workflow",
  "meta": {
    "title": "Simple Order Flow"
  },
  "lanes": [
    { "id": "ui", "label": "User Interface" },
    { "id": "svc", "label": "Service Layer" }
  ],
  "nodes": [
    { "id": "start", "lane": "ui", "col": 0, "type": "frontend", "label": "Start" },
    { "id": "process", "lane": "svc", "col": 1, "type": "backend", "label": "Process" },
    { "id": "end", "lane": "ui", "col": 2, "type": "frontend", "label": "Finish" }
  ],
  "edges": [
    { "from": "start", "to": "process" },
    { "from": "process", "to": "end" }
  ]
}

```

## Key Source Files

Understanding the Archify workflow diagram specification requires consulting these canonical files in the `tt-a1i/archify` repository:

1. **[`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json)** – Complete JSON Schema with `required` arrays, type definitions, and validation rules
2. **[`archify/examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-tool-call.workflow.json)** – Production-ready example demonstrating all optional sections
3. **[`archify/renderers/workflow/README.md`](https://github.com/tt-a1i/archify/blob/main/archify/renderers/workflow/README.md)** – Renderer implementation notes for `meta` key support
4. **[`docs/authoring-cookbook.md`](https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md)** – High-level patterns for schema-compliant authoring

## Summary

- **Seven mandatory fields** define every Archify workflow diagram: `schema_version`, `diagram_type`, `meta` (with `title`), `lanes`, `nodes`, and `edges`
- **Schema version 2** is current; version 1 supports legacy migrations
- **Optional `meta` fields** control rendering without structural changes—`animation`, `visual_preset`, and `quality_profile` are commonly used
- **Topology arrays** (`phases`, `groups`, `mainPath`, `semanticChecks`) add visual and semantic depth
- **Validation is strict**: the schema rejects unknown top-level keys or missing required properties

## Frequently Asked Questions

### What happens if I omit `meta.title` in an Archify workflow diagram?

Validation fails. According to [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) lines 8‑14, `meta` itself is required and must contain `title` as a non-empty string. The validator throws a schema violation before rendering begins.

### Can I use `schema_version: 1` for new diagrams?

Version 1 is supported for backward compatibility only. New diagrams should use `schema_version: 2` to access current features including semantic checks and advanced rendering presets. The migration tooling in Archify automatically upgrades version 1 files when detected.

### How do I add styling without breaking schema validation?

Place visual configuration inside `meta` or node/edge-level optional fields. The schema explicitly permits `variant`, `brand`, `visual_preset`, and `quality_profile`—these pass validation and affect renderer output. Never add arbitrary keys at the top level; the schema rejects undefined properties.

### Where is the complete field reference for workflow diagrams?

The authoritative source is [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) in the `tt-a1i/archify` repository. Lines 1‑401 contain type definitions, required arrays, and per-field documentation. For practical patterns, examine [`archify/examples/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/agent-tool-call.workflow.json), which exercises all optional schema features.