How Archify Manages Shared Definitions: Element IDs and Points in JSON Schemas

Archify centralizes reusable schema components in archify/schemas/common.schema.json, allowing various diagram schemas to import canonical definitions for element IDs, coordinate points, and other common types via JSON Schema $ref pointers.

The tt-a1i/archify repository uses a modular JSON Schema architecture where shared definitions eliminate duplication across diagram types. By storing common patterns in a dedicated file, the system ensures that validation logic for element identifiers, geometric coordinates, and enumerated values remains consistent whether you are defining a workflow, dataflow, or architecture diagram.

The Centralized Common Schema

All reusable type definitions live in archify/schemas/common.schema.json. This file acts as the single source of truth for validation rules that appear across multiple diagram schemas.

Rather than redefining what constitutes a valid node ID or coordinate pair in every schema, Archify aggregates these patterns under the standard JSON Schema $defs keyword. This approach allows individual diagram schemas to remain concise while maintaining strict consistency in how they validate inputs.

Core Shared Definitions in $defs

The common schema defines primitives that capture the canonical shape of values used throughout the system.

Element IDs (id)

The id definition enforces a string pattern for identifiers that must begin with a letter and may contain alphanumerics, underscores, or hyphens. This standard applies universally to node IDs, lane IDs, edge IDs, and view IDs across all diagram types.

When a schema needs to validate an identifier, it references this definition rather than duplicating the regex pattern.

Coordinate Points (point)

The point definition specifies a two-element numeric array representing [x, y] coordinates in diagram space. This type supports edge routing configurations (such as via and labelAt properties) and other positional data requirements.

The array constraint ensures that every coordinate pair contains exactly two numbers, preventing malformed geometry in diagrams.

Additional Reusable Primitives

Beyond IDs and points, the common schema defines shared types for:

• locale, animation, visualPreset, and qualityProfile – Configuration enums for rendering and localization
• side and relationshipWidth – Layout and styling constraints
• componentType, brandMark, and variant – UI component categorizations
• legendMode, legendEntry, guidedViews, and cards – Documentation and navigation structures

Each definition uses standard JSON Schema syntax to enforce type safety and valid value ranges.

Referencing Shared Definitions in Diagram Schemas

Individual diagram schemas import these definitions using JSON Schema $ref pointers. For example, archify/schemas/workflow.schema.json validates node identifiers by referencing "common.schema.json#/$defs/id".

This reference pattern creates a dependency graph where the common schema acts as the root authority. When validation runs against a workflow diagram, the validator resolves the $ref pointer to apply the rules defined in common.schema.json.

The same mechanism applies to coordinate data. An edge definition in a workflow schema can specify routing points using "$ref": "common.schema.json#/$defs/point" to ensure all coordinates conform to the standard [x, y] format.

Implementation Examples

The following patterns demonstrate how to reference shared definitions in schema documents:

// Referencing the canonical ID definition
{
  "id": "database_service",
  "$ref": "common.schema.json#/$defs/id"
}

// Validating an array of routing coordinates
{
  "via": [
    [120, 45],
    [300, 78]
  ],
  "$ref": "common.schema.json#/$defs/point"
}

// Using the guidedViews definition for documentation navigation
{
  "guidedViews": [
    {
      "id": "overview",
      "label": "System Overview",
      "focus": ["frontend", "backend"]
    }
  ],
  "$ref": "common.schema.json#/$defs/guidedViews"
}

Summary

• Centralized Authority: All shared definitions reside in archify/schemas/common.schema.json under the $defs keyword.
• Standard References: Diagram schemas import definitions using $ref pointers like "common.schema.json#/$defs/id".
• Consistent Validation: The id type enforces alphanumeric identifiers starting with letters, while the point type guarantees two-element numeric coordinate arrays.
• Extensible Design: Additional shared types (animation presets, legend modes, etc.) follow the same reference pattern, ensuring uniform validation across workflow, architecture, and dataflow diagrams.

Frequently Asked Questions

Where are shared definitions stored in the Archify repository?

All shared definitions are stored in archify/schemas/common.schema.json. This file contains the complete set of $defs (definitions) that specify validation rules for element IDs, coordinate points, and other reusable types used across various diagram schemas.

What pattern does the element ID definition enforce?

The id definition requires strings that start with a letter and may contain alphanumeric characters, underscores, or hyphens. This pattern applies to all identifiers in the system, including node IDs, lane IDs, edge IDs, and view IDs, ensuring consistent naming conventions across diagram types.

How do I reference a coordinate point in a workflow schema?

Use the JSON Schema $ref pointer with the format "common.schema.json#/$defs/point". This reference validates that the property contains a two-element numeric array [x, y], which is required for properties like edge routing coordinates (via) and label positions (labelAt).

Can I use these shared definitions in custom diagram schemas?

Yes. Any schema file can import definitions from the common schema using standard JSON Schema $ref syntax. Simply reference "common.schema.json#/$defs/{definition_name}" to inherit the validation logic for IDs, points, or any other shared type defined in the central repository.

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