# How to Write Valid JSON for the Archify Architecture Diagram Schema

> Learn to write valid JSON for the Archify architecture diagram schema. Ensure required fields like schema_version, diagram_type, meta, and components are correctly formatted for accurate diagrams.

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

---

**To write valid JSON for the Archify architecture diagram schema, your document must include the mandatory top-level fields `schema_version` (set to `1`), `diagram_type` (set to `"architecture"`), a `meta` object containing at least a `title`, and a non-empty `components` array where each element specifies `id`, `type`, `label`, `pos`, and `size` properties.**

The `tt-a1i/archify` repository validates every diagram against a strict JSON Schema defined in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json). This schema enforces type safety, required properties, and structural relationships to ensure diagrams render correctly. Understanding the exact field requirements prevents validation errors when using the Archify CLI or programmatic APIs.

## Mandatory Top-Level Fields

Every architecture diagram JSON must contain four top-level keys as defined in the schema's `required` array.

- **`schema_version`**: Must be the integer `1`. This constant guarantees compatibility with the current schema iteration.
- **`diagram_type`**: Must be the string `"architecture"`. This distinguishes architecture diagrams from other diagram types like workflow or dataflow.
- **`meta`**: An object containing human-readable metadata. At minimum, it must include a `title` string.
- **`components`**: A non-empty array of **Component Objects**. Each object represents a node in your diagram, such as a service, database, or external system.

Omitting any of these fields or providing incorrect types will result in immediate schema validation failures.

## Configuring the Meta Object

The `meta` object controls how Archify renders and labels your diagram. Beyond the required `title`, you can specify several optional properties defined in [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json):

- **`subtitle`**: A short description displayed beneath the title.
- **`output`**: Filename for the generated HTML or PNG output.
- **`animation`**: Entry animation style; accepts `"trace"` or `"none"`.
- **`visual_preset`**: Rendering theme; options include `"classic"`, `"signal-flow"`, `"blueprint"`, or `"editorial"`.
- **`quality_profile`**: Rendering fidelity; choose `"standard"` or `"showcase"`.
- **`engineering_profile`**: Currently only supports `"deployment-ownership"`.
- **`repository`**: An object linking to source code with `url` (GitHub URL) and `revision` (40-character SHA).
- **`viewBox`**: A two-item numeric array `[width, height]` defining the canvas size. The schema enforces minimum values of `320` for width and `240` for height.

## Defining Components

The `components` array is where you declare every visual node. The schema validates each component against definitions imported from [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) and local constraints. Each component requires:

- **`id`**: A unique string identifier referenced by connections and boundaries.
- **`type`**: A predefined category such as `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, or `external`.
- **`label`**: A non-empty string displayed on the diagram node.
- **`pos`**: A coordinate pair `[x, y]` defining absolute positioning. This is required unless you use grid-based layout.
- **`size`**: A numeric pair `[width, height]` where both values must be greater than `0`.

Optional component fields include `sublabel` and `tag` for additional labeling, `sources` for code references (file `path` and line numbers), and `row`/`col` indices for grid placement.

## Optional Layout and Positioning

You have two mutually exclusive strategies for component positioning.

**Absolute Positioning**: Provide `pos` arrays directly in each component object. This offers pixel-perfect control but requires manual coordinate management.

**Grid Layout**: Supply a top-level `layout` object with `mode` set to `"grid"`. When using grid mode, components use `row` and `col` properties instead of `pos`. The layout object accepts optional geometry controls:

- `origin`: Starting coordinates `[x, y]`.
- `cols`: Number of columns.
- `gapX`, `gapY`: Spacing between cells.
- `cellW`, `cellH`: Cell dimensions.

If you omit the `layout` object entirely, Archify defaults to absolute positioning and requires `pos` in every component.

## Visual Relationships: Boundaries and Connections

To group components or draw arrows between them, use the optional `boundaries` and `connections` arrays.

**Boundaries** create visual groupings like regions or security zones. Each boundary object requires:
- `kind`: Either `"region"` or `"security-group"`.
- `label`: Display text for the boundary.
- `wraps`: An array of component `id` strings to enclose.
- `pad` (optional): Padding in pixels.

**Connections** define directed edges between components. Required fields are `from` and `to`, both referencing component `id`s. Optional connection properties include:
- `label` and `variant` for styling (e.g., `"emphasis"`, `"security"`, `"dashed"`).
- `fromSide` and `toSide` for anchor points (`"left"`, `"right"`, `"top"`, `"bottom"`).
- `route` for path calculation (`"auto"`, `"straight"`, `"orthogonal-h"`, `"orthogonal-v"`).
- `via` for manual routing through intermediate points.
- `width` for line thickness (minimum `0.5`).

## Validating Your JSON

Archify provides a CLI validation command to check your document against [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) before rendering.

```bash

# Using the Archify CLI

archify validate my-diagram.json

# Using ajv-cli (Node.js)

npm install -g ajv-cli
ajv validate -s archify/schemas/architecture.schema.json -d my-diagram.json

```

Validation errors reference specific schema violations, such as missing required fields or type mismatches in `components`.

## Complete JSON Examples

### Minimal Valid Diagram

This example satisfies all mandatory requirements without optional fields:

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Minimal Service"
  },
  "components": [
    {
      "id": "api",
      "type": "backend",
      "label": "API Server",
      "pos": [100, 100],
      "size": [120, 60]
    }
  ]
}

```

### Full-Featured Production Example

For a complete implementation demonstrating boundaries, connections, and advanced meta options, reference the official example in [`archify/examples/web-app.architecture.json`](https://github.com/tt-a1i/archify/blob/main/archify/examples/web-app.architecture.json):

```json
{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Sample Web App",
    "subtitle": "Classic 3-tier SaaS on AWS",
    "output": "web-app-rendered.html",
    "quality_profile": "showcase",
    "visual_preset": "classic",
    "viewBox": [800, 600]
  },
  "components": [
    {
      "id": "cdn",
      "type": "cloud",
      "label": "CloudFront",
      "pos": [200, 100],
      "size": [140, 70]
    },
    {
      "id": "api",
      "type": "backend",
      "label": "API Gateway",
      "pos": [400, 100],
      "size": [140, 70]
    }
  ],
  "boundaries": [
    {
      "kind": "region",
      "label": "AWS Region",
      "wraps": ["cdn", "api"]
    }
  ],
  "connections": [
    {
      "from": "cdn",
      "to": "api",
      "label": "HTTPS",
      "variant": "emphasis"
    }
  ]
}

```

## Summary

- **Four mandatory top-level fields**: `schema_version` (1), `diagram_type` ("architecture"), `meta` (with `title`), and `components` (non-empty array).
- **Component requirements**: Each node needs `id`, `type`, `label`, `pos` (unless using grid), and `size` (both dimensions > 0).
- **Positioning modes**: Use absolute `pos` coordinates or define a `layout` object with `mode: "grid"` and `row`/`col` indices.
- **Relationships**: Add `boundaries` to group components visually and `connections` to draw arrows with optional routing hints.
- **Validation**: Run `archify validate <file>` or use `ajv` against [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json) to catch schema violations early.

## Frequently Asked Questions

### What are the mandatory fields for an Archify architecture diagram?

Your JSON must include `schema_version` set to `1`, `diagram_type` set to `"architecture"`, a `meta` object containing at least a `title` string, and a `components` array with at least one element. Each component must have `id`, `type`, `label`, `pos`, and `size` properties according to the schema defined in [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/architecture.schema.json).

### How do I position components without using a grid layout?

Omit the top-level `layout` object and provide a `pos` array `[x, y]` inside each component object. The `pos` coordinates use absolute pixel positioning within the canvas defined by `meta.viewBox`. This approach gives you direct control over node placement without grid constraints.

### What component types are supported in the schema?

The schema defines specific allowed values for the `type` property including `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, and `external`. These types determine the visual iconography and styling applied to each node in the rendered diagram.

### How can I validate my Archify JSON before rendering?

Use the Archify CLI command `archify validate <filename>` to check your document against the official schema. Alternatively, use any JSON Schema validator like `ajv` or Python's `jsonschema` library, pointing to [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json) and [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) for complete type definitions.