What Is the Purpose of the `archify/schemas/` Directory?

The archify/schemas/ directory contains JSON Schema definitions that enforce a strict structural contract for Archify's intermediate representation (IR), validating diagram JSON before rendering and guaranteeing backward compatibility across all diagram types.

The archify/schemas/ directory in the tt-a1i/archify repository serves as the formal validation layer between author-written diagram definitions and the rendering pipeline. These schemas ensure that only well-structured, version-controlled JSON data reaches Archify's typed renderers, preventing runtime errors and maintaining consistency across workflow, sequence, dataflow, lifecycle, and architecture diagrams.

Core Function of the archify/schemas/ Directory

The primary purpose of this directory is to house JSON Schema definitions that describe the exact shape of the intermediate representation (IR) used by Archify’s typed renderers. Each schema enforces a strict contract that serves three critical functions:

• Pre-render validation of author-written diagram JSON occurs before any layout calculations or rendering begins.
• Backward compatibility is guaranteed through a constant schema_version: 1, ensuring files validated today continue working in future releases.
• Runtime validation operates without external dependencies by utilizing bundled AJV validators stored in renderers/shared/generated-validators.mjs.

Schema Architecture and Key Files

The directory organizes schemas by diagram type, with shared definitions centralized for maintainability.

Diagram-Specific Schemas

Each supported diagram type maintains its own top-level schema file that defines domain-specific structures:

• workflow.schema.json — Defines structures for lanes, phases, and nodes used in workflow diagrams.
• sequence.schema.json — Specifies participants and messages for sequence diagrams.
• dataflow.schema.json — Describes stages and flows for dataflow diagrams.
• lifecycle.schema.json — Outlines states and transitions for lifecycle diagrams.
• architecture.schema.json — Details components and connections for architecture diagrams.

Shared Definitions

The common.schema.json file provides reusable $defs referenced by all diagram schemas. According to the source code in tt-a1i/archify, this includes shared definitions for identifiers, points, locales, brand marks, and legend entries, ensuring consistent data types across different diagram types without duplication.

Validation Workflow and Runtime Integration

Archify implements a two-tier validation strategy that separates development-time flexibility from runtime performance.

During development, you can validate diagrams using standard AJV implementations against the raw schema files. However, at runtime, Archify employs pre-compiled validators located in renderers/shared/generated-validators.mjs. These generated validators are applied automatically by each renderer through the getValidator function exported from renderers/shared/validator.mjs.

This architecture eliminates the need for external validation dependencies in production environments while maintaining strict type safety.

How to Validate Diagrams Against Archify Schemas

You can validate diagram JSON manually using Node.js and AJV, or utilize Archify's built-in validation utilities.

Manual Validation with AJV

Validate a workflow diagram against its schema directly:

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

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

if (!validate(diagram)) {
  console.error("Schema validation failed:", validate.errors);
  process.exit(1);
}
console.log("Diagram is valid!");

Using Archify's Bundled Validators

For runtime validation using the repository's generated validators:

import { getValidator } from "renderers/shared/validator.mjs";

async function loadAndValidate(path, type) {
  const { validator } = await getValidator(type); // e.g. "workflow"
  const doc = await fetch(path).then(r => r.json());
  const result = validator(doc);
  if (!result) console.error(validator.errors);
  else console.log("Valid!");
}

Summary

• The archify/schemas/ directory defines the formal JSON Schema contract for Archify's intermediate representation.
• Five diagram-specific schemas (workflow.schema.json, sequence.schema.json, dataflow.schema.json, lifecycle.schema.json, architecture.schema.json) enforce type safety for their respective domains.
• common.schema.json provides shared definitions for identifiers, points, and locales used across all schemas.
• Runtime validation uses pre-generated AJV validators in renderers/shared/generated-validators.mjs to ensure zero-dependency validation.
• A constant schema_version: 1 guarantees backward compatibility for validated diagram files.

Frequently Asked Questions

What schema version does Archify use?

Archify uses schema_version: 1 across all schemas in the archify/schemas/ directory. This version remains constant to ensure backward compatibility, meaning diagram files validated against the current schema will continue to work in future releases of the tt-a1i/archify repository.

How does Archify validate diagrams without external dependencies?

The repository bundles generated AJV validators in renderers/shared/generated-validators.mjs. These pre-compiled validators are accessed via the getValidator function in renderers/shared/validator.mjs, allowing renderers to validate diagram structure at runtime without requiring the AJV library as a production dependency.

Can I validate my diagram JSON manually before using Archify?

Yes. You can import any schema file (such as workflow.schema.json or sequence.schema.json) directly into your Node.js application and compile it with AJV. This approach allows you to catch validation errors during development before submitting diagrams to the Archify rendering pipeline.

What happens if my diagram fails schema validation?

If validation fails, the renderer returns detailed error objects describing which schema constraints were violated. This occurs before any layout or rendering logic executes, preventing malformed data from reaching the rendering pipeline and ensuring that only well-structured JSON produces visual output.

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