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

> Discover the purpose of the archify/schemas/ directory. It uses JSON Schema to enforce structural contracts for Archify's IR, validating diagram JSON and ensuring backward compatibility.

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

---

**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`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json)** — Defines structures for `lanes`, `phases`, and `nodes` used in workflow diagrams.
- **[`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/sequence.schema.json)** — Specifies `participants` and `messages` for sequence diagrams.
- **[`dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/dataflow.schema.json)** — Describes `stages` and `flows` for dataflow diagrams.
- **[`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json)** — Outlines `states` and `transitions` for lifecycle diagrams.
- **[`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json)** — Details `components` and `connections` for architecture diagrams.

### Shared Definitions

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

```javascript
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:

```javascript
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`](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), [`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json), [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json)) enforce type safety for their respective domains.
- **[`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json) or [`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/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.