Archify Schema Common Shared Definitions: Complete Reference Guide

Archify's JSON Schema definitions reuse a centralized set of primitives from 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. 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:

{
  "$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

{
  "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

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

Brand Integration in Diagrams

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

Schema Files That Consume Common Definitions

File	Purpose
archify/schemas/common.schema.json	Central $defs repository
archify/schemas/workflow.schema.json	Top-level workflow definitions
archify/schemas/sequence.schema.json	Sequence diagram schema
archify/schemas/lifecycle.schema.json	Lifecycle diagram schema
archify/schemas/dataflow.schema.json	Data-flow diagram schema

Summary

• 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, 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.

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