Schema Definitions That Govern IR for Each Archify Diagram Type

Archify validates every diagram's Internal Representation (IR) against a dedicated JSON Schema file that enforces type-specific structural constraints while inheriting common definitions for consistent component typing across all formats.

The tt-a1i/archify repository stores all diagrams as JSON IR that must pass strict schema validation before rendering. Understanding what schema definitions govern IR for each Archify diagram type is essential for programmatic diagram generation and custom tooling. Each supported format—from architecture to lifecycle—maintains its own schema file in archify/schemas/, all extending a shared foundation defined in common.schema.json.

Architecture Diagram Schema

The architecture diagram IR uses archify/schemas/architecture.schema.json to validate grid-based component layouts.

Root requirements include:

• schema_version
• diagram_type = "architecture"
• meta (title, visual preset, viewBox, legend)
• components

Each component object requires an id and a type field chosen from the enum: frontend, backend, database, cloud, security, messagebus, or external. Positioning data uses either row/col grid coordinates or absolute pos/size values.

Workflow Diagram Schema

Workflow diagrams implement swim-lane visualization through archify/schemas/workflow.schema.json.

Required top-level properties:

• schema_version
• diagram_type = "workflow"
• meta
• lanes (vertical swim-lanes with id and label)
• nodes (placed within lanes)
• edges (connections between nodes)

Nodes specify their lane placement via lane and col fields, while edges support visual variants including default, emphasis, security, and dashed.

Sequence Diagram Schema

Sequence diagrams validate participant interactions through archify/schemas/sequence.schema.json.

The schema mandates:

• schema_version
• diagram_type = "sequence"
• meta
• participants (objects with id, type, and label)
• messages (interaction lines)

Messages connect participant IDs through from and to fields positioned at a vertical y coordinate. Visual variants extend beyond workflow options to include return lines for reply messages.

Dataflow Diagram Schema

Pure data-pipeline diagrams conform to archify/schemas/dataflow.schema.json, which mirrors workflow structure but optimizes for data movement semantics.

Required fields:

• schema_version
• diagram_type = "dataflow"
• meta
• components (using standard component types)
• connections

Connections support explicit routing strategies via the routing property, accepting values of auto, straight, or orthogonal-h/v.

Lifecycle Diagram Schema

State-machine and lifecycle diagrams use archify/schemas/lifecycle.schema.json to validate stage progression.

Root requirements include:

• schema_version
• diagram_type = "lifecycle"
• meta
• stages
• transitions

Stages define their semantic role through a type enum: start, active, success, or error. Transitions connect stage IDs and may include a variant property for visual emphasis.

Common Schema Foundation

All diagram-specific schemas reference archify/schemas/common.schema.json through JSON Schema $ref pointers. This shared foundation provides reusable $defs for:

• id format validation
• componentType enum (frontend, backend, database, cloud, security, messagebus, external)
• Legend entries
• Guided views
• Point coordinates

By centralizing these definitions, Archify guarantees that component type strings, identifier formats, and legend structures remain consistent across architecture, workflow, sequence, dataflow, and lifecycle diagrams.

Validating IR Against Schemas

Archify uses the AJV validator to enforce schema compliance at runtime. Below is a practical implementation pattern for validating different diagram types:

import Ajv from "ajv";
import architectureSchema from "./archify/schemas/architecture.schema.json";
import workflowSchema from "./archify/schemas/workflow.schema.json";
import sequenceSchema from "./archify/schemas/sequence.schema.json";
import dataflowSchema from "./archify/schemas/dataflow.schema.json";
import lifecycleSchema from "./archify/schemas/lifecycle.schema.json";

const ajv = new Ajv({ allErrors: true });

const validators = {
  architecture: ajv.compile(architectureSchema),
  workflow: ajv.compile(workflowSchema),
  sequence: ajv.compile(sequenceSchema),
  dataflow: ajv.compile(dataflowSchema),
  lifecycle: ajv.compile(lifecycleSchema)
};

function validateDiagram(ir, type) {
  const validate = validators[type];
  if (!validate(ir)) {
    console.error(`${type} IR validation errors:`, validate.errors);
    return false;
  }
  return true;
}

// Usage example
const archIR = {
  schema_version: "1.0",
  diagram_type: "architecture",
  meta: { title: "System Overview" },
  components: []
};

if (validateDiagram(archIR, "architecture")) {
  console.log("IR is valid and ready for rendering");
}

Each validator checks the incoming JSON against its corresponding schema in archify/schemas/, ensuring that required fields exist, component types match the allowed enum values, and structural relationships like lane assignments or stage transitions follow the defined constraints.

Summary

• Five dedicated schemas govern IR for Archify's diagram types: architecture.schema.json, workflow.schema.json, sequence.schema.json, dataflow.schema.json, and lifecycle.schema.json.
• Common foundation at archify/schemas/common.schema.json provides shared $defs for IDs, component types, and legends, ensuring consistency across all formats.
• Strict validation requires root fields including schema_version, diagram_type, and type-specific collections like components, lanes, participants, or stages.
• Component type enum remains identical across schemas, supporting frontend, backend, database, cloud, security, messagebus, and external classifications.
• AJV compilation is used at runtime to validate IR before rendering, as implemented in the tt-a1i/archify source code.

Frequently Asked Questions

What file path contains the schema for Archify architecture diagrams?

The architecture diagram schema resides at archify/schemas/architecture.schema.json in the repository root. This file defines the required components array structure and the positioning schema for grid-based layouts using either row/column coordinates or absolute positioning.

How does Archify ensure consistent component typing across different diagram formats?

All diagram schemas reference archify/schemas/common.schema.json via JSON Schema $ref pointers. This shared schema defines the componentType enum and ID formats that every diagram type must use, ensuring that terms like backend or database have identical meaning in architecture, workflow, and sequence diagrams.

Can I validate an Archify IR file programmatically without using the Archify application?

Yes. You can import the raw JSON Schema files from archify/schemas/ and compile them using any JSON Schema validator like AJV. Instantiate the validator with the specific diagram type schema, then call the compiled validation function against your IR object to receive detailed error messages if the structure violates the schema constraints.

What distinguishes the workflow schema from the dataflow schema in Archify?

While both use nodes and connections, workflow.schema.json emphasizes swim-lane visualization with lanes, nodes, and edges properties, whereas dataflow.schema.json focuses on pipeline semantics with components and connections that support explicit routing algorithms like orthogonal-h/v. The dataflow schema omits lane-based positioning in favor of connection routing strategies.

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