# Required Fields for Every Archify Diagram Schema: A Complete Guide

> Discover the required fields for every Archify diagram schema, including schema_version, diagram_type, and meta. Learn essential components for Architecture and Workflow diagrams.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: api-reference
- Published: 2026-08-30

---

**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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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

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

```

### Workflow Diagram

```json
{
  "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

```json
{
  "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

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json)** – Defines Architecture diagram validation rules.
- **[`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json)** – Contains Workflow-specific constraints and version compatibility.
- **[`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/sequence.schema.json)** – Specifies Sequence diagram participant and message requirements.
- **[`dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/dataflow.schema.json)** – Validates Data Flow stage and node structures.
- **[`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json), [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json), [`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/sequence.schema.json), [`dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/dataflow.schema.json)) and [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json), which contains reusable definitions for types like identifiers and component categories used across all diagram specifications.