# What Is the Purpose of `common.schema.json` in Archify?

> Discover the purpose of common.schema.json in Archify. This file centralizes shared JSON Schema definitions for consistent validation across all diagram schemas.

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

---

**The [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) file serves as Archify's centralized repository of shared JSON Schema definitions, providing reusable types for identifiers, locales, component enums, and UI patterns that ensure consistent validation across all diagram schemas.**

Archify is a schema-driven framework for validating architecture diagrams including workflows, sequences, dataflows, and lifecycles. The [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) file located at [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) functions as the foundational layer of this validation architecture, eliminating code duplication and establishing a single source of truth for cross-cutting concerns.

## The Role of [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) in Schema Architecture

The primary function of this file is to house **shared type definitions** under the `$defs` keyword, making them available to all specialized diagram schemas through JSON Schema's `$ref` mechanism. This centralization ensures that concepts like identifier patterns, localization settings, and visual presets maintain identical validation rules regardless of where they appear.

### Centralized Type Definitions

Within [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json), critical reusable types are defined once and referenced everywhere. These include:

- **`id`** – Pattern constraints for diagram identifiers
- **`locale`** – Language and region specifications
- **`componentType`** – Classification enums for architectural components
- **`brandMark`** – Branding and visual identity formats
- **Point** – Coordinate structures for spatial positioning
- **UI enums** – Animation styles, visual presets, and legend modes

By maintaining these definitions centrally, Archify guarantees that tightening validation rules—such as enforcing stricter `id` patterns—propagates immediately to all diagram types without requiring individual schema modifications.

## Integration with the AJV Validation Pipeline

The [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) file is integral to Archify's code-generation pipeline. The script at `scripts/generate-validators.mjs` explicitly loads this schema first before processing diagram-specific schemas, ensuring that all shared definitions are registered in the AJV (Another JSON Schema Validator) instance.

```javascript
// scripts/generate-validators.mjs (excerpt)
import Ajv2020 from 'ajv/dist/2020.js';
import fs from 'node:fs';
import path from 'node:path';

const schemasDir = path.join(root, 'schemas');
const ajv = new Ajv2020({ allErrors: true, strict: true });

// Load common definitions first
ajv.addSchema(JSON.parse(fs.readFileSync(path.join(schemasDir, 'common.schema.json'), 'utf8')));

// Subsequent diagram schemas inherit these definitions

```

This loading sequence ensures that validators generated for [`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), and other diagram types automatically recognize and enforce the shared constraints defined in the common schema.

## Referencing Common Types in Diagram Schemas

Individual diagram schemas reference definitions from [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) using standardized `$ref` pointers. For example, [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) imports the locale definition rather than redefining it:

```json
{
  "$ref": "common.schema.json#/$defs/locale"
}

```

This reference pattern appears throughout Archify's schema ecosystem, including in [`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). The approach eliminates redundancy while ensuring that the semantic contract tests in `archify/test/workflow-semantic-contract.test.mjs` validate against identical type constraints across all diagram formats.

## Programmatic Validation with Common Schema

When validating diagrams programmatically, developers must explicitly add the common schema to their AJV instance to resolve cross-schema references:

```javascript
import Ajv from 'ajv';
import commonSchema from './archify/schemas/common.schema.json' assert { type: 'json' };

const ajv = new Ajv();
ajv.addSchema(commonSchema);

const validate = ajv.getSchema('https://github.com/tt-a1i/archify/schemas/common.schema.json');
const data = { id: 'myDiagram' };

console.log(validate(data)); // Validates against the shared id pattern

```

This pattern ensures that runtime validation matches the static schema definitions used during code generation.

## Summary

- **[`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json)** acts as the single source of truth for shared validation types across all Archify diagram schemas.
- The file defines reusable `$defs` including identifiers, locales, component types, and UI enums that eliminate duplication.
- **`scripts/generate-validators.mjs`** loads this schema first to ensure generated validators inherit shared constraints.
- Diagram schemas reference common types via `$ref` pointers like `common.schema.json#/$defs/locale`.
- Centralized maintenance allows global validation rule updates by editing a single file.

## Frequently Asked Questions

### How does [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) reduce maintenance overhead in Archify?

By centralizing shared type definitions in [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json), the file eliminates the need to duplicate validation logic across [`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), and other diagram schemas. When you need to update a shared rule—such as modifying the regex pattern for the `id` field—you only modify [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json), and all dependent schemas automatically receive the updated validation logic through their `$ref` references.

### What specific types are defined in [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json)?

The schema defines fundamental reusable types under `$defs` including: **`id`** (identifier patterns), **`locale`** (language/region codes), **`componentType`** (architectural component classifications), **`brandMark`** (visual branding formats), **Point** (spatial coordinates), and various UI-related enums for animation styles and legend modes. These definitions enforce consistent terminology across Archify's validation pipeline.

### Why must `generate-validators.mjs` load [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) before other schemas?

The script at `scripts/generate-validators.mjs` loads [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) first using `ajv.addSchema()` because diagram-specific schemas contain `$ref` pointers that resolve to definitions within the common schema. AJV requires these definitions to be registered in the validator instance before it can compile schemas that reference them, ensuring the generated validation modules contain complete logic for both shared and diagram-specific constraints.

### Can I use [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) independently for custom validation?

Yes, you can import and use [`common.schema.json`](https://github.com/tt-a1i/archify/blob/main/common.schema.json) standalone in any AJV-based validation workflow. The schema is self-contained and exposes its definitions under the `$defs` property, making it suitable for validating isolated data structures against Archify's standard types like identifiers or locales without loading the full diagram schema ecosystem.