Modeling Overview

WarmHub gives you three primitives — shapes, things, and assertions — connected by wrefs. Before diving into each one, it helps to understand the principles that make them work together.

Core Principles

Everything is versioned, nothing is deleted. Every mutation produces a new version. 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, existing references automatically resolve to the new name. 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, but know that renaming is safe if needed. See Naming as Navigation for a deep dive on 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 a belief. 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
Patterns & Recipes	Common modeling patterns that work well in practice