The IR schema and governed registries for ArchSmith — the structural contract a diagram intermediate representation (IR) must satisfy, and the catalog of colors/sub-layer types it's allowed to reference.

See the root README for what ArchSmith is and how the pieces fit together; this package is the schema layer only, consumed by @archsmith/renderer for validation.

Files

diagram-schema.json — JSON Schema (draft 2020-12) for the IR: the document a human or agent produces describing a layered architecture, and that @archsmith/renderer validates and renders to SVG. Fixed shape: 5 columns, Core Platform sub-layers stacked in order, systems-of-record as a sibling section below the "deployed on" wrapper.
registries/sub-layers.json — the governed, extensible list of Core Platform sub-layer types (Discovery and Governance, Execution and Capability Layer, Entity Layer, Systems of Record and Knowledge).
registries/colors.json — the governed color catalog. The standard family is fully populated; accessible (a colorblind/contrast-safe palette) has the right structure but no values yet — tracked here.
registries/icons.json — placeholder only. Categories that will need icons are listed; no actual icon tokens are defined yet, deliberately, to avoid inventing bespoke icon shapes ad hoc — tracked here. Items without an icon render as a plain colored dot.

Usage

import { getDiagramSchema, getRegistry, listRegistryNames } from "@archsmith/schema";

const schema = getDiagramSchema(); // the parsed diagram-schema.json
const colors = getRegistry("colors"); // one governed registry, parsed
listRegistryNames(); // ["sub-layers", "colors", "icons"]

In practice you'll rarely call this package directly — @archsmith/renderer's validate()/render() already do, and @archsmith/mcp-server exposes the schema and each registry as MCP resources for an agent to read live.

Editor support

Use the stable, versioned schema URL in an ArchSmith document to enable JSON autocomplete and inline validation in compatible editors:

{
  "$schema": "https://ayeshlk.github.io/archsmith/schema/0.3.0/diagram-schema.json",
  "schemaVersion": "0.3.0"
}

Versioned URLs remain immutable. https://ayeshlk.github.io/archsmith/schema/latest/diagram-schema.json follows the newest schema and is useful for discovery, but committed diagrams should use the versioned URL for reproducibility.

Governance model

Changing diagram-schema.json's structure, or adding an entry to any registry, is a deliberate change-request event — never a decision made by a generation step or an end user mid-diagram. This is what keeps the format a consistent house style rather than free-form per-diagram layout. Bump schemaVersion/registryVersion on any such change.

What stays free per diagram (no change request needed): which already-approved sub-layers/colors/icons a given diagram uses, how many rows of boxes a layer has, and whether a notes callout is included. Only the standard color family is currently selectable; accessible remains a governed placeholder until its palette is complete.