# What Is the Purpose of `common.schema.json` in Archify? The Central Shared Definitions File Explained

> Discover the purpose of common.schema.json in Archify. This central file holds shared definitions, primitive types, enumerations, and reusable objects for all diagram schemas.

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

---

**[`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) is the central "shared definitions" file for Archify's JSON-Schema-based diagram specifications, storing primitive types, enumerations, and reusable objects that are referenced across all diagram schemas.**

In the Archify repository (`tt-a1i/archify`), diagram validation relies on a modular JSON Schema architecture. Rather than duplicating type definitions in every diagram schema—[`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), and others—the project centralizes common structures in a single file. This article explains how [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) works, why it matters, and how to use it when extending Archify's validation system.

## What [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) Contains

The file begins with a **`$defs`** object that declares each reusable piece. These definitions cover identifiers, locales, animation settings, visual presets, component types, brand marks, and geometric structures.

```json
{
  "$defs": {
    "id": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$" },
    "locale": { "enum": ["en", "zh-CN"] },
    "animation": { "enum": ["trace", "none"] },
    "visualPreset": { "enum": ["classic", "signal-flow", "blueprint", "editorial"] },
    "point": {
      "type": "object",
      "properties": {
        "x": { "type": "number" },
        "y": { "type": "number" }
      },
      "required": ["x", "y"]
    }
  }
}

```

Additional shared definitions include:

- **`relationshipWidth`** – standardized edge thickness values
- **`cards`** – reusable card container structures
- **`legendEntry`** – legend item formatting
- **`brandMark`** – brand identifier specifications

## How Diagram Schemas Reference [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json)

Other schemas import these definitions using JSON Schema **`$ref`** syntax. In [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json), you will find references like:

```json
{
  "properties": {
    "locale": { "$ref": "common.schema.json#/$defs/locale" },
    "animation": { "$ref": "common.schema.json#/$defs/animation" },
    "id": { "$ref": "common.schema.json#/$defs/id" }
  }
}

```

This pattern repeats across [`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), and [`lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/lifecycle.schema.json)—every diagram type follows the same conventions through shared references.

## Three Core Benefits of [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json)

### 1. Consistency Across Diagram Types

Every diagram schema uses the exact same definition for identifiers, locales, animation settings, and visual presets. A workflow diagram and a sequence diagram both validate `id` fields against the identical pattern: `^[a-zA-Z][a-zA-Z0-9_-]*$`.

### 2. Maintainability Through Single-Point Updates

Changing a shared rule requires editing only one file. If you tighten the `id` pattern or add a new `locale` option, the change propagates automatically to all dependent schemas. This eliminates the risk of inconsistent validation rules drifting across diagram types.

### 3. Reduced Code Duplication

Common structures like `point`, `relationshipWidth`, `cards`, and `legendEntry` are defined once and `$ref`‑ed wherever needed. Without [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json), each diagram schema would need to redeclare these structures, increasing file size and error potential.

## Practical Usage Examples

### Referencing Shared Definitions in a Custom Schema

When creating a new diagram type, reference [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) to inherit Archify's standard conventions:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "My Custom Diagram",
  "type": "object",
  "properties": {
    "nodeId": { "$ref": "common.schema.json#/$defs/id" },
    "locale": { "$ref": "common.schema.json#/$defs/locale" },
    "brand": { "$ref": "common.schema.json#/$defs/brandMark" }
  },
  "required": ["nodeId"]
}

```

### Using the `point` Definition for Polyline Edges

Geometric references use the same pattern. Here, a `via` array for routing edges through intermediate points:

```json
{
  "type": "object",
  "properties": {
    "via": {
      "type": "array",
      "items": { "$ref": "common.schema.json#/$defs/point" }
    }
  }
}

```

### Programmatic Validation with AJV

In JavaScript applications, load [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) as a base schema before compiling dependent schemas:

```javascript
import Ajv from "ajv";
import commonSchema from "./archify/schemas/common.schema.json";
import workflowSchema from "./archify/schemas/workflow.schema.json";

const ajv = new Ajv({ schemas: [commonSchema] });
const validate = ajv.compile(workflowSchema);

const diagram = {/* … JSON diagram … */};
if (!validate(diagram)) {
  console.error(validate.errors);
}

```

The `schemas: [commonSchema]` option makes `$ref` resolution work correctly across file boundaries.

## Key Files in the Schema Architecture

| File | Role |
|------|------|
| [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) | Central repository of shared definitions (`$defs`) used by all diagram schemas. |
| [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) | Defines workflow diagram structure; heavily references [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json). |
| [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) | Schema for sequence diagrams using shared definitions. |
| [`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json) | Data-flow diagram validation relying on common types. |
| [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) | Lifecycle diagram schema built from shared components. |

## Summary

- **[`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json)** serves as the single source of truth for reusable schema components in Archify.
- The **`$defs`** object contains primitive types, enumerations, and complex objects referenced via **`$ref`**.
- Centralizing definitions ensures **consistency**, **maintainability**, and **reduced duplication** across all diagram schemas.
- All diagram types—workflow, sequence, dataflow, lifecycle—inherit their core validation rules from this file.

## Frequently Asked Questions

### What happens if I modify [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json)?

Modifications apply immediately to all schemas that reference the changed definitions. This is powerful for global updates but requires caution: tightening validation rules may invalidate existing diagram files. Test changes against sample diagrams in `archify/schemas/` before committing.

### Can I extend [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) with custom definitions?

Yes. Add new entries to the `$defs` object following the existing naming conventions, then reference them with `"$ref": "common.schema.json#/$defs/yourNewDef"`. Keep definitions generic enough that multiple diagram types can reuse them; diagram-specific structures belong in their respective schema files.

### Why does Archify use separate schema files instead of one large schema?

Modular schemas allow selective loading and faster validation. A tool that only processes workflow diagrams can compile [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json) without loading sequence or lifecycle definitions. This architecture also enables independent versioning of diagram types as Archify evolves.

### How do I validate a diagram against [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) directly?

You generally should not—[`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) contains definitions, not a root schema. Instead, validate against a concrete diagram schema (like [`workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json)) that references the common definitions. The validator resolves all `$ref` pointers automatically during compilation.