# Archify Schema Common Shared Definitions: Complete Reference Guide

> Explore Archify's common shared definitions in this reference guide. Learn how centralized primitives ensure consistent identifiers, styling, and UI elements across all diagram types in the tt-a1i/archify repository.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: api-reference
- Published: 2026-09-06

---

**Archify's JSON Schema definitions reuse a centralized set of primitives from [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) to ensure consistent identifiers, localization, visual styling, and UI elements across all diagram types.**

The Archify repository organizes its schema architecture around a single source of truth for reusable definitions. Rather than duplicating type constraints across workflow, sequence, lifecycle, and dataflow schemas, the project centralizes common building blocks in [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json). This approach simplifies validation, guarantees backwards compatibility, and enables rapid schema evolution.

## Core Shared Definitions in common.schema.json

The `$defs` section of the common schema exports the following reusable types. Each definition is referenced throughout the codebase using standard JSON Schema `$ref` pointers.

### Identification and Referencing

- **`id`** — Canonical identifier for any object. Accepts string UUIDs or semantic identifiers. Referenced by nodes, edges, components, and cards.
- **`items`** — Array of `id` references. Used when collections of IDs are required, such as component groupings.

### Localization and Text

- **`locale`** — Localizable text object supporting language keys like `en`, `zh`, and others. Powers workflow, sequence, lifecycle, and dataflow titles and descriptions.

### Visual Styling and Animation

- **`animation`** — Animation specification including type, duration, and easing functions for transitions.
- **`visualPreset`** — Preset values for color palettes, themes, and visual styles consumed by renderers.
- **`qualityProfile`** — Output quality controls such as image resolution and compression settings for raster pipelines.

### UI Components and Layout

- **`guidedViews`** — Instructional view configurations with steps, tooltips, and focus zones for user onboarding flows.
- **`legendMode`** — Enum controlling legend rendering: `compact` or `expanded`.
- **`legendEntry`** — Single legend entry combining label, color, and icon properties.
- **`componentType`** — Enum of categories: `service`, `database`, `UI`, `external`, and others. Determines iconography and color coding.
- **`brandMark`** — Branding assets including logo URL, color, and placement rules.
- **`variant`** — UI widget variants: `primary`, `secondary`, `danger`, etc. Used by buttons, badges, and tags.
- **`point`** — 2-D coordinate with `x` and `y` properties for node positioning and edge routing.
- **`cards`** — Collection of UI cards with title, body, and actions for info panels.
- **`relationshipWidth`** — Edge thickness settings for diagram connectors.
- **`side`** — Placement hints (`left`, `right`, `top`, `bottom`) for attached UI elements.

## How References Work in Archify Schemas

Definitions are consumed via `$ref` pointers following this pattern:

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

```

This indirection allows any top-level schema to inherit updates from the common schema without structural changes.

## Practical Usage Examples

### Component Definition Using Shared Primitives

```json
{
  "type": "object",
  "properties": {
    "id": { "$ref": "common.schema.json#/$defs/id" },
    "label": { "$ref": "common.schema.json#/$defs/locale" },
    "type": { "$ref": "common.schema.json#/$defs/componentType" },
    "position": { "$ref": "common.schema.json#/$defs/point" },
    "legend": {
      "type": "object",
      "properties": {
        "mode": { "$ref": "common.schema.json#/$defs/legendMode" },
        "entries": {
          "type": "array",
          "items": { "$ref": "common.schema.json#/$defs/legendEntry" }
        }
      }
    }
  },
  "required": ["id", "label", "type"]
}

```

### Multi-Language Title Field

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

```

### Brand Integration in Diagrams

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

```

## Schema Files That Consume Common Definitions

| File | Purpose |
|------|---------|
| [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json) | Central `$defs` repository |
| [`archify/schemas/workflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) | Top-level workflow definitions |
| [`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) | Sequence diagram schema |
| [`archify/schemas/lifecycle.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/lifecycle.schema.json) | Lifecycle diagram schema |
| [`archify/schemas/dataflow.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/dataflow.schema.json) | Data-flow diagram schema |

## Summary

- **[`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json)** provides **14 core shared definitions** covering identification, localization, visual styling, and UI components.
- **All top-level schemas** reference these definitions via `$ref` pointers, ensuring type consistency.
- **Key reusable types** include `id`, `locale`, `componentType`, `point`, `animation`, `guidedViews`, and `brandMark`.
- This architecture enables **centralized validation** with AJV and **backwards-compatible schema evolution**.

## Frequently Asked Questions

### How do I add a new reusable definition to Archify schemas?

Add the definition to the `$defs` object in [`archify/schemas/common.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/common.schema.json), then reference it from dependent schemas using `"$ref": "common.schema.json#/$defs/yourNewDef"`. Update any consuming schemas to import the new type as needed.

### Can I override a common definition in a specific schema?

JSON Schema does not support `$ref` overrides directly. Instead, wrap the common definition with `allOf` or compose it with additional `properties` in the consuming schema to extend or constrain the base type.

### What validation library does Archify use for these schemas?

According to the repository structure, Archify uses **AJV** (Another JSON Schema Validator) for runtime validation, leveraging the centralized `$defs` to compile efficient validation functions once and reuse them across diagram types.