Modeling Overview

WarmHub gives you three primitives — shapes, things, and assertions — connected by wrefs. The usual flow is to define a shape and create a thing, then — when attribution, confidence, or multiple perspectives matter — assert about it. Not every model needs that last step.

The modeling lifecycle

Company and Assessment here are example shapes you define — not built-ins.

# 1. Define the shapes — one for the entity, one for a claim about it
wh shape create Company --repo myorg/myrepo --fields '{"name":"string","domain":"string"}'
wh shape create Assessment --repo myorg/myrepo --fields '{"verdict":"string","confidence":"number"}'

# 2. Create a thing — an entity with one canonical state
wh thing create Company/acme --repo myorg/myrepo --data '{"name":"Acme Corp","domain":"acme.com"}'

# 3. Assert about it — attribution and confidence, kept separate from the entity's state
wh assertion create --shape Assessment --about Company/acme --repo myorg/myrepo --data '{"verdict":"competitor","confidence":0.8}'

Each write is versioned, and the assertion’s about target is fixed at creation — see the principles below. From here, the detail pages cover each primitive in depth.

Core Principles

A few principles make these primitives work together.

Everything is versioned, nothing is deleted. Every change to a thing’s data produces a new version — an in-place rename is the exception, since it edits identity, not data. Retraction hides an entity from default queries but preserves its full history. This means you can always ask “what did we know at time T?” — so don’t be afraid to write data early, even if it’s uncertain.

Writes are versioned per operation. A write can contain multiple operations. Use this to keep related changes close together — add a thing and its initial assertions in the same write instead of spreading them across separate requests.

Names are stable, not permanent. Names identify things and appear in wrefs (references like Shape/name), but they can be changed — even on retracted things. When a thing is renamed, identity-based references — assertion targets, collection members, and durable ids — follow it automatically, but a wref that uses the old name stops resolving. Things are linked by identity, not by name — the name is a human-readable label on top of that link. Choose names that are meaningful and stable, and prefer durable ids for long-lived keys. See Retract, Rename & Schema Changes for the full rename behavior and Naming as Navigation for designing effective names.

The about reference is immutable. An assertion’s target is set at creation and cannot be changed. If you assert about the wrong thing, retract it and create a new assertion. This immutability guarantees that the relationship between an assertion and its subject is stable and auditable.

Choosing Your Primitives

The most common modeling question is: should this be a thing or an assertion?

Use things when you’re modeling entities with a single canonical state — the objects your system reasons about. A company, a sensor, a document. If there’s one truth about this entity, it’s a thing. See Things — When to Use Things for details.

Use assertions when attribution, confidence, or multiple perspectives matter — when you need to know who said something about an entity, not just the current state. An agent’s assessment, a probabilistic claim, a scored evaluation. See Assertions — When to Use Assertions for details.

Not everything needs to be an assertion. A lookup table of country codes is fine as plain things. An agent’s assessment of whether a competitor is a threat — that’s an assertion.

What’s in This Section

Page	What it covers
Shapes	Schema definitions with typed fields and constraints
Things	Named, versioned entities — the core data objects
Naming as Navigation	How hierarchical names create navigable knowledge structures
Assertions	Claims about things — with immutable targets and version pinning
Wrefs	The addressing system — how to reference any entity
Collections	Pair, Triple, Set, and List — built-in grouping
Retract, Rename & Schema Changes	What happens to references when you retract, rename, or evolve a shape
Patterns & Recipes	Common modeling patterns that work well in practice