# Schema for Archify Architecture Diagrams: Structure, Validation, and Examples

> Explore the Archify architecture diagram schema defined in JSON Schema. Understand structure, validation rules, and find practical examples to guide your diagram creation.

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

---

**The schema for Archify architecture diagrams is defined in the JSON Schema file [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json), which specifies required top-level fields including `schema_version`, `diagram_type`, `meta`, and `components`, and references shared type definitions from [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json).**

The `tt-a1i/archify` repository provides a structured format for defining architecture diagrams as code. Understanding the **schema for Archify architecture diagrams** is essential for creating valid diagrams that can be rendered and validated by the toolchain. This schema ensures consistency across diagram definitions by enforcing strict typing for components, connections, layouts, and metadata.

## Schema Location and Core Structure

The definitive schema resides in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) within the repository. This file serves as the single source of truth for what constitutes a valid architecture diagram in the Archify ecosystem.

### Primary Schema File

The [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) file defines the required top-level fields and allowed properties for each diagram. According to the `tt-a1i/archify` source code, every valid architecture diagram must include `schema_version`, `diagram_type`, `meta`, and `components` at the root level. The schema also specifies optional constructs for connections between components, layout boundaries, and diagram-specific visual attributes.

### Shared Type Definitions

Rather than duplicating type definitions, the architecture schema references [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json). This shared file provides reusable types including:
- **`id`** – Unique identifier format for components
- **`point`** – Coordinate definitions for positioning
- **`componentType`** – Enumerated types of architectural elements
- **`variant`** – Styling and display variants

This modular approach ensures that type definitions remain consistent across different diagram formats in the project.

## Required Fields and Diagram Structure

A valid Archify architecture diagram must conform to the following structure as defined in the schema:

- **`schema_version`** – Integer identifying the schema revision (currently version 1)
- **`diagram_type`** – Must be set to `"architecture"` for this schema
- **`meta`** – Object containing metadata such as `title`, `description`, and `author`
- **`components`** – Array of component objects, each requiring an `id`, `type`, and `label`

Additional optional fields include `connections` for defining relationships between components, `boundaries` for grouping elements, and `layout` options for controlling visual presentation.

## Validating Architecture Diagrams

You can validate diagram files against the schema using JavaScript validation libraries, direct schema references, or the built-in Archify CLI.

### Programmatic Validation with AJV

For Node.js applications, use the `ajv` library to compile and validate against the schema:

```javascript
import fs from 'fs';
import Ajv from 'ajv';
import addFormats from 'ajv-formats';

// Load schema
const schema = JSON.parse(
  fs.readFileSync(
    new URL('../archify/schemas/architecture.schema.json', import.meta.url),
    'utf8'
  )
);

// initialise validator
const ajv = new Ajv({ allErrors: true });
addFormats(ajv);
const validate = ajv.compile(schema);

// Example diagram JSON (a minimal valid architecture diagram)
const diagram = {
  schema_version: 1,
  diagram_type: 'architecture',
  meta: { title: 'Sample Architecture' },
  components: [{ id: 'svc-1', type: 'service', label: 'Service 1' }]
};

// Validate
const valid = validate(diagram);
if (!valid) console.error(validate.errors);
else console.log('Diagram is valid!');

```

### Schema References in Diagram Files

You can reference the schema directly within your JSON diagram files using the `$schema` property:

```json
{
  "$schema": "https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json",
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { "title": "My System" },
  "components": [
    {
      "id": "db",
      "type": "database",
      "label": "PostgreSQL"
    }
  ]
}

```

### CLI Validation

The Archify CLI provides built-in validation against the official schema:

```bash

# Assuming the CLI is installed globally

archify validate --schema archify/schemas/architecture.schema.json \
                  --input examples/archify-repo.architecture.json

```

## Related Schema Files

The `archify/schemas/` directory contains additional schemas for different diagram types. While [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) handles system architecture diagrams, the repository also includes:

- **[`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json)** – Schema for workflow and process diagrams
- **[`sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/sequence.schema.json)** – Schema for sequence diagrams
- **[`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json)** – Schema for component lifecycle diagrams  
- **[`dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/dataflow.schema.json)** – Schema for data flow diagrams

Each of these schemas extends the base definitions found in [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json), maintaining type consistency across the entire Archify diagram ecosystem.

## Summary

- The **schema for Archify architecture diagrams** is located at [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) in the `tt-a1i/archify` repository.
- Required fields include `schema_version`, `diagram_type`, `meta`, and `components`.
- The schema references [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) for shared types like `id`, `point`, and `componentType`.
- Validation can be performed programmatically using AJV, via the `$schema` reference in JSON files, or through the `archify validate` CLI command.

## Frequently Asked Questions

### Where is the schema for Archify architecture diagrams located?

The schema resides at [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) in the repository root. This file defines the complete JSON Schema specification for architecture diagrams, including all required fields, component properties, and validation rules used by the Archify toolchain.

### What are the required fields in an Archify architecture diagram?

Every architecture diagram must include four top-level fields: `schema_version` (integer), `diagram_type` (set to `"architecture"`), `meta` (object containing at minimum a title), and `components` (array of component objects). Each component within the array must have an `id`, `type`, and `label` property.

### How do I validate an architecture diagram against the schema?

You can validate diagrams using three methods: programmatically with the AJV library in Node.js by compiling [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json), by including the `"$schema"` reference in your JSON file pointing to the schema URL, or by running the command `archify validate --schema archify/schemas/architecture.schema.json --input <your-file>.json` in the terminal.

### What is the relationship between architecture.schema.json and common.schema.json?

The [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) file references [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) for reusable type definitions. This includes fundamental types like `id` for unique identifiers, `point` for coordinates, `componentType` for element classifications, and `variant` for styling options. This shared approach ensures that type definitions remain synchronized across all diagram schemas in the Archify project.