# Key Schema Arrays for Each Archify Diagram Type: The Complete Reference

> Discover the essential schema arrays for each Archify diagram type: Architecture, Workflow, Sequence, Dataflow, and Lifecycle. Unlock diagram structure details with this complete reference.

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

---

**Archify defines five diagram families—Architecture, Workflow, Sequence, Dataflow, and Lifecycle—each exposing specific top-level array properties in their JSON Schema files that hold the diagram’s structural elements.**

The tt-a1i/archify repository validates diagram definitions using strict JSON Schema files located in the `archify/schemas/` directory. Understanding the key schema arrays for each Archify diagram type allows you to author valid diagram JSON files that render correctly across the five supported families. These top-level arrays act as entry points where you populate objects that satisfy the referenced component-type definitions.

## Architecture Diagram Schema Arrays

The Architecture diagram type uses [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) to validate system structure diagrams. This schema exposes four primary array properties that define visual boxes, containment regions, and connectivity.

- **`components`** – The visual boxes representing system parts (frontend, backend, database, cloud, security, messagebus, external).
- **`boundaries`** – Optional region or security-group wrappers that visually group components.
- **`connections`** – Links between component IDs that form the edges of the diagram.
- **`cards`** – Optional overlay cards attached to the diagram for additional metadata.

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { "title": "Sample Architecture" },
  "components": [
    { "id": "ui",   "type": "frontend",   "label": "UI" },
    { "id": "api",  "type": "backend",    "label": "API" },
    { "id": "db",   "type": "database",   "label": "DB" }
  ],
  "connections": [
    { "from": "ui",  "to": "api",  "variant": "default" },
    { "from": "api", "to": "db",   "variant": "default" }
  ]
}

```

## Workflow Diagram Schema Arrays

Workflow diagrams in [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) support complex pipeline visualization with eight distinct array properties. These arrays control horizontal lanes, execution phases, grouping constructs, and semantic validation rules.

- **`lanes`** – Horizontal tracks that group nodes (for example, "dev" or "ci").
- **`phases`** – Optional higher-level bands spanning columns across lanes.
- **`groups`** – Named boxes that span a specific lane and column range.
- **`nodes`** – Individual boxes representing steps (frontend, backend, cloud, etc.).
- **`edges`** – Directed connections between node IDs.
- **`cards`** – Optional overlay cards for metadata.
- **`mainPath`** – An ordered list of node IDs defining the primary execution path.
- **`semanticChecks`** – Rules including `allowedRoots`, `allowedTerminals`, `requiredEdges`, and `requiredPaths`.

```json
{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { "title": "CI Pipeline" },
  "lanes": [{ "id": "dev", "label": "Dev" }],
  "nodes": [
    { "id": "checkout", "lane": "dev", "col": 0, "type": "frontend", "label": "Checkout" },
    { "id": "build",    "lane": "dev", "col": 1, "type": "backend",  "label": "Build" }
  ],
  "edges": [
    { "from": "checkout", "to": "build", "role": "main" }
  ]
}

```

## Sequence Diagram Schema Arrays

Sequence diagrams use [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) to model interactions over time. The schema defines five array properties that manage lifelines, messages, and activation bars.

- **`participants`** – The lifelines representing actors (frontend, backend, external, etc.).
- **`messages`** – Arrows between participants including optional `variant` and `note` properties.
- **`segments`** – Optional horizontal separator lines that divide the diagram.
- **`activations`** – Vertical activation bars linked to specific participants.
- **`cards`** – Optional overlay cards attached to the diagram.

```json
{
  "schema_version": 1,
  "diagram_type": "sequence",
  "meta": { "title": "Client‑Server Interaction" },
  "participants": [
    { "id": "client", "type": "frontend", "label": "Client" },
    { "id": "server", "type": "backend",  "label": "Server" }
  ],
  "messages": [
    { "from": "client", "to": "server", "y": 200, "label": "GET /data" },
    { "from": "server", "to": "client", "y": 300, "label": "200 OK" }
  ]
}

```

## Dataflow Diagram Schema Arrays

Dataflow diagrams in [`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json) model data transformation pipelines using four primary arrays. These define processing stages, the nodes within those stages, and the flow between them.

- **`stages`** – Ordered processing steps, each with an ID, label, and optional `type`.
- **`nodes`** – Individual boxes living inside a stage (frontend, backend, database, cloud, security, messagebus, external).
- **`edges`** – Directed connections between node IDs with optional `variant`, `route`, and routing helpers.
- **`cards`** – Optional overlay cards for additional context.

```json
{
  "schema_version": 1,
  "diagram_type": "dataflow",
  "meta": { "title": "ETL Pipeline" },
  "stages": [
    { "id": "extract", "label": "Extract" },
    { "id": "transform", "label": "Transform" },
    { "id": "load", "label": "Load" }
  ],
  "nodes": [
    { "id": "src", "stage": "extract", "type": "external", "label": "Source DB" },
    { "id": "proc", "stage": "transform", "type": "backend", "label": "Processor" },
    { "id": "dest", "stage": "load", "type": "database", "label": "Warehouse" }
  ],
  "edges": [
    { "from": "src", "to": "proc" },
    { "from": "proc", "to": "dest" }
  ]
}

```

## Lifecycle Diagram Schema Arrays

The Lifecycle diagram type defined in [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) models state machines with three core array properties. These arrays capture states, transitions between them, and optional metadata overlays.

- **`states`** – Nodes representing lifecycle states (start, active, success, error, etc.).
- **`transitions`** – Directed edges connecting states with optional `variant`, `role`, and routing hints.
- **`cards`** – Optional overlay cards for additional diagram information.

```json
{
  "schema_version": 1,
  "diagram_type": "lifecycle",
  "meta": { "title": "Job Lifecycle" },
  "states": [
    { "id": "queued",   "type": "start",    "label": "Queued" },
    { "id": "running",  "type": "active",   "label": "Running" },
    { "id": "finished", "type": "success",  "label": "Finished" }
  ],
  "transitions": [
    { "from": "queued",   "to": "running",  "variant": "default" },
    { "from": "running",  "to": "finished", "variant": "default" }
  ]
}

```

## Summary

The key schema arrays for each Archify diagram type serve as the structural foundation for all visual representations in the tt-a1i/archify repository.

- **Architecture** diagrams rely on `components`, `boundaries`, `connections`, and `cards`.
- **Workflow** diagrams utilize eight arrays including `lanes`, `nodes`, `edges`, `mainPath`, and `semanticChecks`.
- **Sequence** diagrams use `participants`, `messages`, `segments`, `activations`, and `cards`.
- **Dataflow** diagrams structure data pipelines through `stages`, `nodes`, `edges`, and `cards`.
- **Lifecycle** diagrams model state machines using `states`, `transitions`, and `cards`.

Populating these top-level arrays with properly typed objects ensures your diagram JSON validates against the corresponding schema files.

## Frequently Asked Questions

### What is the difference between components and nodes in Archify schemas?

**`components`** appear exclusively in Architecture diagrams within [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) to represent high-level system parts like databases and services. **`nodes`** appear in Workflow, Dataflow, and other diagram types to represent individual steps or processing units within lanes or stages. While both define visual boxes, components connect via `connections` while nodes use `edges`.

### Which schema array defines the execution order in Workflow diagrams?

The **`mainPath`** array in [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) defines the ordered list of node IDs that constitute the primary execution path through the workflow. This array works alongside the **`edges`** array to determine both the visual layout and logical flow of the diagram.

### How do I add overlay information to any Archify diagram type?

Every Archify diagram schema includes a **`cards`** array that accepts overlay card objects. These cards attach metadata to the diagram without affecting the primary structural layout. You can populate the `cards` array in Architecture, Workflow, Sequence, Dataflow, and Lifecycle diagrams to provide additional context.

### Are boundaries required in Architecture diagrams?

No, the **`boundaries`** array in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) is optional. Boundaries serve as visual wrappers or security-group regions around components, but valid Architecture diagrams require only the `components` array and optionally `connections`. Omit boundaries when your diagram does not require logical containment groups.