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

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 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 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, 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 ids 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.

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 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

{
  "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
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 labels, and optional styling types 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 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 to maintain cross-diagram consistency.

Frequently Asked Questions

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

Archify uses the .sequence.json extension for sequence diagram data files, as demonstrated by 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 ids, 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. 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. This file contains reusable patterns for id formats, label constraints, and base styling properties that sequence.schema.json references via JSON Schema $ref pointers, ensuring consistent validation rules across all diagram schemas in the repository.

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