Where to Find JSON Schema Definitions for Archify Diagrams

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	archify/schemas/workflow.schema.json
Sequence diagram	sequence.schema.json	archify/schemas/sequence.schema.json
Lifecycle diagram	lifecycle.schema.json	archify/schemas/lifecycle.schema.json
Dataflow diagram	dataflow.schema.json	archify/schemas/dataflow.schema.json
Architecture diagram	architecture.schema.json	archify/schemas/architecture.schema.json
Common reusable definitions	common.schema.json	archify/schemas/common.schema.json

The 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

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

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

{
  "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 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	Lanes, swimlanes, node sequencing, parallel flows
archify/schemas/sequence.schema.json	Participants, lifelines, message ordering, activation boxes
archify/schemas/lifecycle.schema.json	States, transitions, initial/final state markers
archify/schemas/dataflow.schema.json	Processes, data stores, external entities, data flows
archify/schemas/architecture.schema.json	Clusters, boundaries, component hierarchies, deployment nodes
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
• 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 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 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.

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