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

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, sequence.schema.json, dataflow.schema.json, lifecycle.schema.json, and others—the project centralizes common structures in a single file. This article explains how common.schema.json works, why it matters, and how to use it when extending Archify's validation system.

What 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.

{
  "$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

Other schemas import these definitions using JSON Schema $ref syntax. In archify/schemas/workflow.schema.json, you will find references like:

{
  "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, dataflow.schema.json, and lifecycle.schema.json—every diagram type follows the same conventions through shared references.

Three Core Benefits of 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, 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 to inherit Archify's standard conventions:

{
  "$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:

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

Programmatic Validation with AJV

In JavaScript applications, load common.schema.json as a base schema before compiling dependent schemas:

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	Central repository of shared definitions ($defs) used by all diagram schemas.
archify/schemas/workflow.schema.json	Defines workflow diagram structure; heavily references common.schema.json.
archify/schemas/sequence.schema.json	Schema for sequence diagrams using shared definitions.
archify/schemas/dataflow.schema.json	Data-flow diagram validation relying on common types.
archify/schemas/lifecycle.schema.json	Lifecycle diagram schema built from shared components.

Summary

• 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?

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 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 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 directly?

You generally should not—common.schema.json contains definitions, not a root schema. Instead, validate against a concrete diagram schema (like workflow.schema.json) that references the common definitions. The validator resolves all $ref pointers automatically during compilation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}