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

> Discover how Archify manages shared definitions like element IDs and points in JSON schemas. Learn about reusable components and `$ref` pointers for efficient diagram schema management.

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

---

**Archify centralizes reusable schema components in [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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:

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

```

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

```

```json
// 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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.