Archify Workflow Diagram Key Fields: Complete Schema Reference

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 (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 requirements:

{
  "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 – Complete JSON Schema with required arrays, type definitions, and validation rules
2. archify/examples/agent-tool-call.workflow.json – Production-ready example demonstrating all optional sections
3. archify/renderers/workflow/README.md – Renderer implementation notes for meta key support
4. 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 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 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, which exercises all optional schema features.

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