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

The 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 file located at 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 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, 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 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.

// 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, 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 using standardized $ref pointers. For example, archify/schemas/workflow.schema.json imports the locale definition rather than redefining it:

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

This reference pattern appears throughout Archify's schema ecosystem, including in dataflow.schema.json and 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:

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 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 reduce maintenance overhead in Archify?

By centralizing shared type definitions in archify/schemas/common.schema.json, the file eliminates the need to duplicate validation logic across workflow.schema.json, 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, and all dependent schemas automatically receive the updated validation logic through their $ref references.

What specific types are defined in 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 before other schemas?

The script at scripts/generate-validators.mjs loads 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 independently for custom validation?

Yes, you can import and use 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.

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