# Where to Find JSON Schema Definitions for Archify Diagrams

> Find Archify diagram JSON schema definitions in the archify/schemas directory. Discover detailed schemas for each diagram type, adhering to JSON-Schema 2020-12. Access the TT-a1i Archify repository for comprehensive technical d...

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

---

**Archify stores all JSON Schema definitions in the `archify/schemas` directory, with separate schema files for each diagram type following the JSON-Schema 2020-12 specification.**

The Archify open-source repository uses strict JSON Schema validation to ensure every diagram file conforms to a well-defined structure. Understanding where these schemas live and how they work is essential for anyone building custom validators, IDE extensions, or automated diagram generators.

---

## Location of JSON Schema Files in the Repository

All **JSON schema definitions for Archify diagrams** reside in the `archify/schemas` directory of the `tt-a1i/archify` repository. Each diagram type has a dedicated schema file, plus a shared definitions file for reusable components.

| Diagram Type | Schema File | Direct Link |
|--------------|-------------|-------------|
| Workflow diagram | [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json) | [archify/schemas/workflow.schema.json](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) |
| Sequence diagram | [`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/sequence.schema.json) | [archify/schemas/sequence.schema.json](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) |
| Lifecycle diagram | [`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json) | [archify/schemas/lifecycle.schema.json](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) |
| Dataflow diagram | [`dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/dataflow.schema.json) | [archify/schemas/dataflow.schema.json](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json) |
| Architecture diagram | [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) | [archify/schemas/architecture.schema.json](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) |
| Common reusable definitions | [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) | [archify/schemas/common.schema.json](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) |

The [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) file contains cross-cutting definitions—IDs, locales, animation presets, legend entries—that other schemas reference via `$ref` pointers. This modular approach prevents duplication and ensures consistency across all diagram types.

---

## What the Schemas Define

Each **JSON schema definition for Archify diagrams** specifies:

- **Required top-level properties**: `schema_version`, `diagram_type`, `meta`, `nodes`, `edges`
- **Diagram-specific structures**: `lanes` for workflows, `participants` for sequences, `states` for lifecycles
- **Allowed values and constraints**: enums for node types, regex patterns for IDs, array length limits
- **Visual rendering hints**: color presets, layout directives, animation configurations

The schemas follow **JSON-Schema 2020-12**, enabling modern validation features like dynamic references and vocabulary extensibility.

---

## How Archify Uses These Schemas

Archify's validation pipeline dynamically selects schemas based on the `diagram_type` field in each diagram JSON. The **AJV validator** (Another JSON Schema Validator) performs the actual conformance checking.

### Validation Flow

1. Parse incoming diagram JSON
2. Extract `diagram_type` value (e.g., `"workflow"`, `"sequence"`)
3. Load matching schema from `archify/schemas/{type}.schema.json`
4. Compile and execute validation with AJV
5. Return detailed error locations if validation fails

This prevents malformed diagrams from reaching the rendering engine and provides precise feedback to users.

---

## Validating Diagrams Against Archify Schemas

You can reuse **Archify's JSON schema definitions** in your own tooling. Below are practical implementation patterns.

### Static Validation with a Known Schema

```javascript
import Ajv from "ajv";
import workflowSchema from "./archify/schemas/workflow.schema.json";
import diagramJson from "./my-diagram.json";

const ajv = new Ajv({ allErrors: true });
const validate = ajv.compile(workflowSchema);
const valid = validate(diagramJson);

if (!valid) {
  console.error("Diagram validation errors:", validate.errors);
} else {
  console.log("Diagram is valid!");
}

```

The `allErrors: true` option ensures you capture every violation, not just the first failure.

### Dynamic Schema Selection by Diagram Type

```javascript
import Ajv from "ajv";
import workflow from "./archify/schemas/workflow.schema.json";
import sequence from "./archify/schemas/sequence.schema.json";

const schemas = {
  workflow,
  sequence,
  lifecycle: require("./archify/schemas/lifecycle.schema.json"),
  dataflow: require("./archify/schemas/dataflow.schema.json"),
  architecture: require("./archify/schemas/architecture.schema.json")
};

function validateDiagram(diagram) {
  const ajv = new Ajv({ allErrors: true, strict: false });
  const schema = schemas[diagram.diagram_type];
  
  if (!schema) {
    throw new Error(`Unsupported diagram type: ${diagram.diagram_type}`);
  }

  const validate = ajv.compile(schema);
  const ok = validate(diagram);
  return { ok, errors: validate.errors };
}

```

This pattern mirrors Archify's internal validator implementation. It scales cleanly when new diagram types are added.

---

## Example: Valid Workflow Diagram JSON

Here's a minimal valid diagram that passes [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json) validation:

```json
{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { 
    "title": "User Checkout Flow",
    "description": "E-commerce purchase workflow"
  },
  "lanes": [
    { "id": "ui", "label": "User Interface" },
    { "id": "backend", "label": "API Services" }
  ],
  "nodes": [
    { "id": "start", "lane": "ui", "label": "Start", "type": "entry" },
    { "id": "checkout", "lane": "ui", "label": "Checkout", "type": "action" },
    { "id": "process", "lane": "backend", "label": "Process Order", "type": "action" }
  ],
  "edges": [
    { "from": "start", "to": "checkout", "label": "Proceed" },
    { "from": "checkout", "to": "process", "label": "Submit" }
  ]
}

```

Running this through AJV with [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json) returns valid. Missing `schema_version`, unknown `diagram_type` values, or malformed `nodes` entries would trigger specific, line-accurate error reports.

---

## Schema File Reference

| File | Purpose |
|------|---------|
| [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) | Lanes, swimlanes, node sequencing, parallel flows |
| [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) | Participants, lifelines, message ordering, activation boxes |
| [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) | States, transitions, initial/final state markers |
| [`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json) | Processes, data stores, external entities, data flows |
| [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) | Clusters, boundaries, component hierarchies, deployment nodes |
| [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) | Shared `$ref` targets: `id` patterns, `locale` objects, `visualPreset` definitions |

Browse these files directly in the repository to inspect property specifications, constraint expressions, and cross-schema relationships.

---

## Summary

- **JSON schema definitions for Archify diagrams** are located in `archify/schemas/` with one file per diagram type plus [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json)
- Schemas follow **JSON-Schema 2020-12** and are consumed by the **AJV validator**
- The `diagram_type` field determines which schema applies during validation
- You can reuse these schemas in external tools for IDE autocomplete, CI validation, or custom generators
- [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) centralizes reusable definitions referenced via `$ref` throughout the schema collection

---

## Frequently Asked Questions

### What version of JSON Schema does Archify use?

Archify uses **JSON-Schema 2020-12**, the latest stable specification. This version provides advanced features like dynamic references and annotation collection that Archify leverages for flexible validation rules.

### Can I extend Archify's schemas for custom diagram types?

You can create new schema files following the same structure, but Archify's core validator will reject unknown `diagram_type` values unless you modify the source. For experimental extensions, consider using the [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) as a base—it has the most permissive structure for custom node types.

### How do I get human-readable error messages from AJV validation?

The `validate.errors` array contains machine-readable error objects with `instancePath`, `schemaPath`, and `message` properties. Map these to user-friendly messages by inspecting the `keyword` (e.g., `"required"`, `"type"`, `"enum"`) and formatting the `params` payload accordingly.

### Are the schemas versioned independently of Archify releases?

Each schema file includes a `schema_version` property in its root definitions, and diagram JSON must declare a matching `schema_version`. Archify maintains backward compatibility for at least one major revision, but schema updates are bundled with Archify releases rather than published separately.