# Archify Sequence Diagrams: Complete Guide to Key Fields and JSON Schema

> Discover the essential fields for Archify sequence diagrams: participants, messages, groups, annotations, and metadata. Learn how these elements enable deterministic, D2-compatible visualizations.

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

---

**Archify sequence diagrams require five primary fields—`participants`, `messages`, `groups`, `annotations`, and `metadata`—defined in [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) to render deterministic, D2-compatible visualizations.**

Archify is an open-source diagramming framework hosted at `tt-a1i/archify` that generates architectural visualizations from structured JSON. Understanding the exact field specifications for Archify sequence diagrams ensures your diagrams validate against the canonical schema and render correctly through the sequence diagram engine.

## Core Schema Fields for Archify Sequence Diagrams

The schema at [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) defines the data structure consumed by the rendering pipeline. Every sequence diagram must include `participants` and `messages`, while `groups`, `annotations`, and `metadata` remain optional.

### Participants Array

The **`participants`** field is a required array of objects defining the actors or components displayed horizontally across the diagram. Each participant object requires:

- **`id`**: A unique string identifier used as a reference in message routing
- **`label`**: Human-readable text rendered above the lifeline
- **Optional styling**: `color`, `icon`, or other visual attributes

The order of participants in this array determines their left-to-right placement on the canvas.

### Messages Array

The **`messages`** field is a required ordered array defining the vertical flow of communication. Each message object contains:

- **`from`**: String ID of the sender participant
- **`to`**: String ID of the receiver participant (matches `from` for self-messages)
- **`label`**: Text displayed on the arrow connector
- **`async`**: Boolean indicating dashed asynchronous arrows when `true`
- **`response`**: Boolean enabling return-message styling when `true`
- **`bend`** / **`stretch`**: Numeric layout hints typically set to **0** and **1.0** to enforce strict horizontal message lines without curvature

According to the source code in `archify/renderers/sequence/render-sequence.mjs`, these fields ensure zero-bend horizontal sequencing compatible with D2 rendering rules.

### Groups Array (Optional)

The **`groups`** field defines logical containers for participants or message phases. Each group includes:

- **`id`**: Unique identifier
- **`label`**: Display name for the container
- **`members`**: Array of participant IDs belonging to the group
- **Optional styling**: Visual properties for borders or backgrounds

Groups effectively model lifelines, activation bars, or higher-level architectural phases without altering the underlying message sequence.

### Annotations Array (Optional)

The **`annotations`** field attaches explanatory notes to specific diagram points. Each annotation specifies:

- **`target`**: Reference to a message ID or participant ID
- **`text`**: The note content
- **`position`**: Placement hints such as "left", "right", or "center"

These annotations render as callouts or footnotes without disrupting the vertical message flow.

### Metadata Object (Optional)

The **`metadata`** field stores repository-level provenance information consumed by Archify tooling but ignored by the layout engine. Standard properties include:

- **`version`**: Schema or diagram version string
- **`author`**: Creator identifier
- **`description`**: Free-form documentation text

## How the Fields Interact in the Rendering Pipeline

The `renderSequence` function in `archify/renderers/sequence/render-sequence.mjs` processes these fields through a deterministic layout engine.

**Participants** establish the horizontal axis. The renderer calculates fixed X-coordinates based on array index, ensuring consistent left-to-right positioning regardless of message complexity.

**Messages** drive the vertical timeline. The renderer processes the `messages` array sequentially, drawing arrows from source to target coordinates. Self-messages render as curved arrows when `from` equals `to`, while standard messages remain strictly horizontal per the constraints documented in [`docs/research-visual-evolution-round-46.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-46.md).

**Groups** wrap around participant lifelines visually but do not reorder the underlying sequence. The renderer uses the `members` array to determine bounding boxes without altering message routing.

## Practical Implementation Examples

### Minimal Valid Sequence Diagram

Create a JSON file following the schema structure:

```json
{
  "participants": [
    { "id": "client", "label": "Client", "color": "#4A90E2" },
    { "id": "server", "label": "API Server", "color": "#7ED321" }
  ],
  "messages": [
    { "from": "client", "to": "server", "label": "GET /items", "async": false },
    { "from": "server", "to": "client", "label": "200 OK", "response": true }
  ],
  "groups": [
    {
      "id": "auth_flow",
      "label": "Authentication Phase",
      "members": ["client", "server"]
    }
  ],
  "annotations": [
    { "target": "msg1", "text": "Initial request", "position": "right" }
  ],
  "metadata": { "version": "1.0", "author": "Jane Doe" }
}

```

### Rendering with JavaScript

Import the sequence renderer to generate SVG output:

```javascript
import { renderSequence } from '@archify/renderers/sequence';

const diagramSpec = /* load JSON from above */;
const svgElement = renderSequence(diagramSpec);
document.getElementById('canvas').appendChild(svgElement);

```

The `renderSequence` function validates the input against [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) before constructing the DOM nodes, throwing validation errors for missing required fields like `participants` or malformed message references.

## Key Source Files

Understanding the implementation requires examining these specific files in the `tt-a1i/archify` repository:

- **[`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json)**: Canonical JSON schema defining all field types, constraints, and required properties
- **`archify/renderers/sequence/render-sequence.mjs`**: Core rendering logic implementing the layout engine and D2 SVG generation
- **[`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md)**: Cross-renderer specifications detailing how sequence diagrams share common field patterns with architecture, workflow, and dataflow diagrams
- **[`docs/research-visual-evolution-round-46.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-46.md)**: Design rationale for zero-bend message constraints and lifeline rendering invariants

## Summary

- **Required fields**: Every Archify sequence diagram must include `participants` and `messages` arrays defined in [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json)
- **Layout determinism**: The `messages` array order controls vertical sequencing, while `participants` array order controls horizontal positioning
- **Optional enhancements**: Use `groups` for visual containment, `annotations` for documentation, and `metadata` for versioning
- **Rendering entry point**: Call `renderSequence()` from `archify/renderers/sequence/render-sequence.mjs` after validating your JSON structure
- **Strict constraints**: Keep `bend` at **0** and `stretch` at **1.0** to maintain horizontal message lines compatible with D2 output

## Frequently Asked Questions

### What happens if I omit the participants field in an Archify sequence diagram?

The schema validation will fail. According to [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json), `participants` is a required array that defines the horizontal axis of the diagram. The `renderSequence` function in `archify/renderers/sequence/render-sequence.mjs` expects this field to map message `from` and `to` references to coordinate positions. Without it, the renderer cannot calculate lifeline placements or route arrows.

### How do I create a self-message in Archify sequence diagrams?

Set the `from` and `to` fields to the same participant ID within a message object. When `renderSequence` detects matching identifiers, it renders a curved arrow returning to the same lifeline rather than a horizontal line between distinct participants. You can optionally set `async: true` to render the self-message with a dashed line style.

### Can I reorder participants without changing the message flow?

Yes. The visual left-to-right order strictly follows the `participants` array index order, independent of the `messages` array sequence. You can rearrange participant IDs in the `participants` array to adjust horizontal layout without modifying message routing, provided you maintain consistent ID references in the `from` and `to` fields.

### Where does Archify enforce the zero-bend constraint for message lines?

The constraint is defined in [`docs/research-visual-evolution-round-46.md`](https://github.com/tt-a1i/archify/blob/main/docs/research-visual-evolution-round-46.md) and implemented in `archify/renderers/sequence/render-sequence.mjs`. By default, the renderer sets `bend` to **0** and `stretch` to **1.0** for all messages, ensuring strictly horizontal arrow lines that comply with D2 sequence diagram specifications. Manual adjustment of these values may cause validation warnings depending on your schema version.