# How Sequence Diagram Schemas Are Structured in Archify: A Complete Technical Guide

> Discover how Archify structures sequence diagram schemas using JSON definitions. Learn about participants, messages, and grouping, validated against UML compliance for accurate rendering.

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

---

**Archify structures sequence diagram schemas as JSON definitions that declare participants, ordered messages, and optional grouping segments, all validated against [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) to ensure UML-compliant rendering.**

Archify uses JSON schemas to standardize how sequence diagrams are defined, validated, and rendered across the codebase. Understanding the structure of these **sequence diagram schemas** is essential for contributing new diagrams or extending the tool's visualization capabilities. The repository stores these definitions in the `archify/schemas/` directory, where strict typing ensures consistency between diagram data and the rendering pipeline.

## Core Components of the Sequence Schema

The [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) file defines three top-level collections that map directly to UML sequence diagram concepts. Every valid sequence diagram must implement these structures.

### Participants Array

The **participants** array declares the entities that interact within the diagram. Each participant object requires:

- `id` – A unique identifier used by messages to reference the participant
- `label` – The human-readable name displayed on the diagram
- `type` – Optional styling information (CSS classes or icon names)

This definition is shared with other schema types through [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json), ensuring consistent identifier patterns across all diagram formats.

### Messages Collection

The **messages** array captures ordered communications between participants. According to the schema, each message entry contains:

- `source` – The `id` of the sending participant
- `target` – The `id` of the receiving participant  
- `label` – The textual description (method name, event, or action)
- `type` – The visual style of the arrow (normal, self, return, etc.)
- `bends` / `stretch` – Numeric values controlling line curvature (typically set to `0` or `1` for clean horizontal layouts)

The array order determines the top-to-bottom sequence of interactions in the rendered output.

### Groups and Segments

Optional **groups** provide logical containers that segment messages into blocks (e.g., "transaction" or "lifecycle stage"). Group objects specify:

- `id` – Identifier for the group
- `label` – Caption displayed on the block header
- `messages` – Array of message `id`s belonging to the group, preserving execution order

This structure allows Archify to render activation bars, lifelines, and background colors consistently across different diagram types.

## Schema Validation and Type Safety

Archify enforces schema compliance at build time using JSON Schema validation. The repository implements validation through the `jsonschema` library, ensuring that any user-provided sequence data conforms to the structural contract defined in [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json).

```typescript
import { validate } from 'jsonschema';
import sequenceSchema from './archify/schemas/sequence.schema.json';

function isValidSequence(data: unknown): data is SequenceDiagram {
  const result = validate(data, sequenceSchema);
  return result.valid;
}

```

Validation failures prevent invalid diagrams from entering the rendering pipeline, maintaining visual consistency in the generated gallery.

## Real-World Implementation Example

The file [`archify/examples/cache-miss-request.sequence.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/cache-miss-request.sequence.json) demonstrates a complete implementation following the schema specification. This example includes:

- Three participants (`client`, `api`, `db`) with distinct labels
- Four ordered messages showing request and response flows
- A `groups` array that organizes related messages into a "Cache-Miss" segment

```json
{
  "participants": [
    { "id": "client", "label": "Client" },
    { "id": "api",    "label": "API Server" },
    { "id": "db",     "label": "Database" }
  ],
  "messages": [
    { "source": "client", "target": "api",    "label": "GET /items",      "type": "request" },
    { "source": "api",    "target": "db",     "label": "SELECT * FROM …", "type": "query"   },
    { "source": "db",     "target": "api",    "label": "Rows",            "type": "response"},
    { "source": "api",    "target": "client", "label": "200 OK",          "type": "response"}
  ],
  "groups": [
    {
      "id": "fetch", 
      "label": "Data Fetch",
      "messages": ["1", "2", "3", "4"]
    }
  ]
}

```

## Rendering Pipeline Integration

The `scripts/build-gallery.mjs` script consumes validated sequence schema files to generate visual diagrams. This build process:

1. Loads and validates JSON files against [`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/sequence.schema.json)
2. Maps participant IDs to visual lifelines
3. Renders messages in array order, applying type-specific arrow styles
4. Groups messages into labeled segments for enhanced readability

By maintaining strict separation between schema definition and rendering logic, Archify ensures that changes to visual styling do not require modifications to the underlying **sequence diagram schemas**.

## Summary

- **Participants** require unique `id` values, display `label`s, and optional styling `type`s stored in the `participants` array.
- **Messages** define interactions through `source`, `target`, and `label` properties, with array order determining visual sequence.
- **Groups** organize related messages into logical blocks using the `messages` array property within group objects.
- The [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) file serves as the single source of truth for validation, enforced by `scripts/build-gallery.mjs` during the build process.
- All definitions reuse common patterns from [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) to maintain cross-diagram consistency.

## Frequently Asked Questions

### What file extension does Archify use for sequence diagram data files?

Archify uses the [`.sequence.json`](https://github.com/tt-a1i/archify/blob/main/.sequence.json) extension for sequence diagram data files, as demonstrated by [`archify/examples/cache-miss-request.sequence.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/cache-miss-request.sequence.json). This naming convention allows the build system to distinguish sequence diagrams from other diagram types (such as Entity-Relationship or Flow diagrams) during the gallery generation process.

### How does Archify handle self-referencing messages in sequence diagrams?

The schema supports self-referencing messages through the `type` property within the **messages** array. When `source` and `target` contain identical participant `id`s, setting `type` to `"self"` instructs the renderer to draw a reflexive arrow looping back to the same lifeline, maintaining UML standard notation for self-calls.

### Can sequence diagrams in Archify include activation bars?

Yes, the schema supports **activation bars** through auxiliary fields such as `activationBars` and `lifelineStyle` defined in [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json). These properties allow the rendering engine to visualize method execution duration by drawing rectangular bars overlapping participant lifelines during specific message sequences.

### Where does Archify store shared schema definitions used by multiple diagram types?

Shared definitions reside in [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json). This file contains reusable patterns for `id` formats, `label` constraints, and base styling properties that [`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/sequence.schema.json) references via JSON Schema `$ref` pointers, ensuring consistent validation rules across all diagram schemas in the repository.