# Key Fields for Archify Architecture Diagrams: A Complete Schema Guide

> Discover the key fields for Archify architecture diagrams. Learn the mandatory and optional elements to create strictly validated JSON structures for your diagrams.

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

---

**Archify architecture diagrams require three mandatory root fields—`schema_version`, `diagram_type`, and `meta`—plus a `components` array, with optional objects for `layout`, `boundaries`, `connections`, and `cards` that together define a strictly validated JSON structure.**

The `tt-a1i/archify` repository defines architecture diagrams through a rigid JSON schema that enforces deterministic rendering and versioning. Understanding the key fields for Archify architecture diagrams ensures your infrastructure visualizations validate correctly against the [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) specification and render predictably across different environments.

## Required Root Fields

Every architecture diagram must include four top-level keys. According to the schema defined in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json), these fields form the immutable foundation of the document.

### schema_version

The `schema_version` field is a constant integer set to `1`. This field enables future versioning of the Archify specification while maintaining backward compatibility for existing diagrams.

### diagram_type

This field must contain the string `"architecture"` to distinguish infrastructure diagrams from other diagram types supported by the Archify ecosystem. The value is strictly enforced by the schema enum definition.

### meta

The `meta` object stores human-readable metadata and rendering controls. It requires at least one sub-field:

- **title** (required): The display name of the diagram
- **locale**: Language and region settings
- **subtitle**: Descriptive text displayed beneath the title
- **output**: Target format specifications
- **animation**: Playback controls for generated visuals
- **visual_preset**: Predefined styling profiles
- **quality_profile**: Rendering fidelity settings
- **engineering_profile**: Technical detail density controls
- **repository**: Object containing `url` and `revision` for source linking
- **views**: Alternative display configurations
- **legend**: Object with `mode` and `entries` for diagram keys
- **viewBox**: Coordinate system boundaries for the canvas

### components

The `components` array contains the visual elements of your architecture. Each component object requires three fields:

- **id**: Unique identifier referenced by connections and boundaries
- **type**: Visual category defined in [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) (`frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, or `external`)
- **label**: Display text for the node

Optional component fields include `sublabel`, `tag`, `brand`, `sources`, `row`, `col`, `pos`, and `size`. These types drive visual styling such as icon selection and color coding.

## Optional Structural Fields

Beyond the required root objects, Archify supports four optional arrays that control layout, grouping, relationships, and documentation.

### layout

The `layout` object controls grid-based positioning with fields including `mode` (typically `"grid"`), `origin` coordinates, `cols` count, `gapX` and `gapY` spacing, plus `cellW` and `cellH` dimensions. When omitted, Archify applies automatic layout algorithms.

### boundaries

Boundaries group components into visual regions or security zones. Each boundary entry requires:

- **kind**: Classification of the grouping
- **label**: Display name for the region
- **wraps**: Array of component `id` strings contained within the boundary

### connections

The `connections` array defines directed edges between components. Required fields are `from` and `to`, both referencing component `id` values. Optional routing and styling fields include:

- **label**: Text displayed on the edge
- **variant**: Visual style (`default`, `emphasis`, `security`, or `dashed`)
- **fromSide** and **toSide**: Connection attachment points
- **route**: Path algorithm (`auto`, `straight`, `orthogonal-h`, `orthogonal-v`)
- **via**: Intermediate waypoints
- **labelAt**, **labelDx**, **labelDy**, **labelSegment**: Label positioning controls
- **width**: Line thickness

### cards

The `cards` array attaches informational callouts to the diagram. These objects follow definitions imported from [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) and support rich text content without affecting the core component graph.

## Schema Validation and Constraints

Archify enforces strict validation through JSON Schema constraints. The [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) explicitly sets `"additionalProperties": false` at multiple levels, preventing typos and unsupported fields from passing validation. This strict mode ensures that every diagram adheres to a predictable structure compatible with the rendering engine.

Component types are validated against the `componentType` enum defined in [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json). This centralization allows the Archify team to add new visual categories—such as `ai` or `iot`—in future schema versions while maintaining type safety.

## Practical Implementation

Below is a minimal valid architecture diagram illustrating a three-tier web application:

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Simple Web App",
    "subtitle": "Frontend ↔ Backend ↔ Database"
  },
  "components": [
    { "id": "frontend", "type": "frontend", "label": "React UI" },
    { "id": "backend", "type": "backend", "label": "Node API" },
    { "id": "db", "type": "database", "label": "PostgreSQL" }
  ],
  "connections": [
    { "from": "frontend", "to": "backend", "variant": "default" },
    { "from": "backend", "to": "db", "variant": "default" }
  ]
}

```

For comprehensive examples, reference [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) in the repository, which demonstrates advanced usage of meta controls, layout grids, boundaries, and connection routing. Test fixtures located at [`archify/test/fixtures/v1-baseline/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/test/fixtures/v1-baseline/web-app.architecture.json) provide additional validation examples used by the Archify test suite.

## Summary

- **Required fields** include `schema_version` (constant `1`), `diagram_type` (fixed to `"architecture"`), `meta` (requiring `title`), and the `components` array (requiring `id`, `type`, and `label`).
- **Optional fields** encompass `layout` for grid control, `boundaries` for component grouping, `connections` for relationship edges, and `cards` for documentation.
- **Strict validation** via `"additionalProperties": false` ensures schema compliance and prevents runtime rendering errors.
- **Component types** are centralized in [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) and drive visual styling through categories like `frontend`, `backend`, and `security`.

## Frequently Asked Questions

### What is the minimum valid Archify architecture diagram?

A valid diagram requires the `schema_version` set to `1`, `diagram_type` set to `"architecture"`, a `meta` object containing at least a `title`, and a `components` array with at least one element containing `id`, `type`, and `label` fields. The schema rejects any document missing these required fields or containing undefined properties.

### Where are component types like "frontend" and "database" defined?

Component types are defined in the `componentType` enum within [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json). This schema imports into [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) to validate the `type` field of each component object. The current allowed values include `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, and `external`.

### Can I add custom fields to an Archify diagram?

No. The schema explicitly sets `"additionalProperties": false` at the root level and within component objects. Any custom fields will cause validation errors. To extend functionality, use the `meta` object's supported sub-fields (such as `repository` or `engineering_profile`) or attach information through the `cards` array.

### How do I control the visual routing of connections between components?

Use the `route` field within a connection object to specify path algorithms. Valid options include `auto` (default), `straight`, `orthogonal-h` (horizontal-first elbows), and `orthogonal-v` (vertical-first elbows). Additional positioning controls like `fromSide`, `toSide`, and `via` arrays provide granular control over attachment points and waypoints.