Required Fields for Every Archify Diagram Schema: A Complete Guide

Every Archify diagram schema requires schema_version, diagram_type, and a meta object containing a title, plus type-specific arrays such as components for Architecture diagrams or lanes, nodes, and edges for Workflow diagrams.

The tt-a1i/archify repository defines four distinct diagram types—Architecture, Workflow, Sequence, and Data Flow—each validated against strict JSON Schema definitions. While all schemas share a common core of required properties, each diagram type enforces additional structural fields necessary for rendering.

Core Required Fields Shared Across All Schemas

Regardless of diagram type, every Archify schema mandates three top-level properties defined in the individual schema files under archify/schemas/:

• schema_version – An integer specifying the schema revision. Architecture, Sequence, and Data Flow diagrams require version 1, while Workflow diagrams accept 1 or 2.
• diagram_type – A string enum identifying the diagram category: "architecture", "workflow", "sequence", or "dataflow".
• meta – An object that must contain at least a title string. This field stores diagram metadata and supports additional optional properties like subtitle or author.

These universal requirements ensure consistent versioning and identification across the Archify ecosystem.

Type-Specific Required Fields

Each diagram specialization extends the core schema with unique structural arrays that define the diagram's content. These requirements are explicitly declared in the required arrays within each respective JSON Schema file.

Architecture Diagram Requirements

According to archify/schemas/architecture.schema.json, Architecture diagrams require the core fields plus:

• components – An array of component objects defining system elements like frontends, backends, and databases.

The complete required field list for Architecture is: ["schema_version", "diagram_type", "meta", "components"].

Workflow Diagram Requirements

The workflow.schema.json file defines Workflow diagrams as visual process flows using swim lanes. Beyond the core fields, you must provide:

• lanes – An array defining swim lane divisions.
• nodes – An array of process nodes positioned within lanes.
• edges – An array connecting nodes to show flow direction.

Workflow schemas permit schema_version values of 1 or 2, making them the only type with multiple valid versions.

Sequence Diagram Requirements

As specified in sequence.schema.json, Sequence diagrams require the core fields plus:

• participants – An array defining actors or system components participating in the sequence.
• messages – An array representing calls or data passed between participants.

These fields establish the timeline and interaction patterns characteristic of sequence diagrams.

Data Flow Diagram Requirements

The dataflow.schema.json file mandates the following additional to the core requirements:

• stages – An array defining processing phases or layers in the data pipeline.
• nodes – Data sources, processors, and destinations positioned within stages.
• flows – Connections showing data movement between nodes.

This structure supports multi-stage data pipeline visualization with explicit directional flow definitions.

Minimal Valid JSON Examples

Below are runnable minimal examples satisfying all required fields for each diagram type.

Architecture Diagram

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { "title": "Sample Architecture" },
  "components": [
    {
      "id": "frontend",
      "type": "frontend",
      "label": "Web UI"
    }
  ]
}

Workflow Diagram

{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { "title": "Sample Workflow" },
  "lanes": [{ "id": "lane1", "label": "Main Lane" }],
  "nodes": [
    {
      "id": "start",
      "lane": "lane1",
      "col": 0,
      "type": "start",
      "label": "Start"
    }
  ],
  "edges": []
}

Sequence Diagram

{
  "schema_version": 1,
  "diagram_type": "sequence",
  "meta": { "title": "Sample Sequence" },
  "participants": [
    { "id": "client", "type": "frontend", "label": "Client" },
    { "id": "server", "type": "backend", "label": "Server" }
  ],
  "messages": [
    {
      "from": "client",
      "to": "server",
      "y": 200,
      "label": "Request"
    }
  ]
}

Data Flow Diagram

{
  "schema_version": 1,
  "diagram_type": "dataflow",
  "meta": { "title": "Sample Data Flow" },
  "stages": [{ "label": "Ingest" }, { "label": "Processing" }],
  "nodes": [
    {
      "id": "source",
      "type": "source",
      "label": "Data Source",
      "stage": 0,
      "row": 0
    },
    {
      "id": "processor",
      "type": "processor",
      "label": "Processor",
      "stage": 1,
      "row": 0
    }
  ],
  "flows": [
    {
      "from": "source",
      "to": "processor",
      "label": "stream"
    }
  ]
}

Schema File Locations and Shared Definitions

All schema definitions reside in the archify/schemas/ directory within the repository. The key files include:

• architecture.schema.json – Defines Architecture diagram validation rules.
• workflow.schema.json – Contains Workflow-specific constraints and version compatibility.
• sequence.schema.json – Specifies Sequence diagram participant and message requirements.
• dataflow.schema.json – Validates Data Flow stage and node structures.
• common.schema.json – Provides shared definitions for reusable types like id, componentType, and brandMark referenced across all diagram schemas.

These JSON Schema files enforce type safety through the required property arrays, ensuring that diagram JSON files contain all necessary structural elements before processing.

Summary

• Every Archify diagram requires schema_version, diagram_type, and a meta object with a title property.
• Architecture diagrams additionally require a components array.
• Workflow diagrams require lanes, nodes, and edges arrays, and support schema versions 1 and 2.
• Sequence diagrams require participants and messages arrays.
• Data Flow diagrams require stages, nodes, and flows arrays.
• Schema definitions are located in archify/schemas/ with common.schema.json providing shared type definitions.

Frequently Asked Questions

What happens if I omit a required field from an Archify diagram schema?

JSON Schema validation will fail. The Archify parser validates input files against the schema definitions in archify/schemas/, and missing required fields trigger validation errors before diagram generation begins. Ensure all required arrays contain at least one element, as empty arrays satisfy the schema requirement but may affect rendering logic.

Can I use schema_version 2 for all Archify diagram types?

No. Only Workflow diagrams support schema_version: 2. Architecture, Sequence, and Data Flow diagrams strictly require schema_version: 1 according to their respective schema files. Attempting to use version 2 with other diagram types will result in validation failures during schema checking.

What fields are included in the meta object besides title?

While only title is required within the meta object, the schemas permit optional properties including subtitle, description, author, and version. The common.schema.json file defines these shared metadata types, allowing for rich documentation of diagram purpose and ownership without breaking validation.

Where are the schema definitions located in the repository?

All JSON Schema definitions are stored in the archify/schemas/ directory. This includes individual schema files for each diagram type (architecture.schema.json, workflow.schema.json, sequence.schema.json, dataflow.schema.json) and common.schema.json, which contains reusable definitions for types like identifiers and component categories used across all diagram specifications.

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