The best way to think about BlueIds is as words — words in a shared language of content. Traditional integration is like meeting every new partner and teaching them your words for apple, orange, and dog all over again: every API contract is a private phrasebook, renegotiated forever. In Blue, when two systems use the same word, they mean exactly the same thing — no glossary meeting, no central authority, no prior coordination. Anyone can coin a new word by creating new content; nobody can quietly change what an existing word means.
Identity follows content
Every Blue node — a scalar, a list, a type, an agreement, a workflow — has exactly one BlueId, derived from its content. If your system and mine independently compute the same BlueId, we are not holding similar data. We are holding the same node: the same word, spoken twice.
Change anything — even a description — and the BlueId changes. Same name, different content? Different word. The label was never the identity — which is why preprocessing can safely dissolve friendly type names into exact references: the name was only ever a way of pointing at the word.
Pure references
The collapsed form of any node is:
payment:
blueId: 9Q1jK...
A pure reference has exactly one field. This is invalid:
# Invalid — neither a reference nor a proper extension
blueId: 9Q1jK...
maximumAmount: 30000
To build on a referenced definition, put it in type position and write your overlay outside it:
type:
blueId: 9Q1jK...
maximumAmount: 30000
That's a new node with its own identity — a new word derived from an old one, not a footnote scribbled onto someone else's.
Expansion and collapse
Suppose the payment terms have BlueId X. Collapsed:
terms:
blueId: X
Expanded, after a provider returns content that verifies to X:
terms:
name: Capture After Confirmation
requiredConfirmations: 2
currency: PLN
Same node. Same document identity. Expansion and collapse change representation, never meaning — and content is verified against its BlueId on arrival, so providers don't need to be trusted, only checked.
This is how you walk the graph. Start from nothing but a word:
blueId: 8XkQp...
Expand one level:
name: Weekend Package Agreement
status: assembling
orders:
blueId: 2Wf9c...
payment:
blueId: 9Q1jK...
Expand only the path you care about — /payment — and leave the rest collapsed. You can traverse an arbitrarily large web this way, pulling in exactly what you need and verifying every step: like reading a text and looking up only the words you don't know yet. Expand deliberately, though — some words name libraries. A single BlueId can stand for a full product catalog or years of history, and you rarely need all of it to do today's work.
The guarantee underneath: processing an agreement with one path expanded must give the identical result to processing it fully materialized. Laziness here isn't an optimization; it's semantics.
Canonicalization
Two authors write the same meaning differently — friendly names versus explicit references, compact overlays versus fuller ones. Which bytes get hashed?
Canonicalization answers that. After preprocessing and resolution, it derives the one deterministic identity form for a given meaning, and that is what gets hashed. So:
- Minimization asks: what can the author omit? Output for humans; many valid answers.
- Canonicalization asks: what exact node is identified? Output for the algorithm; exactly one answer.
Different spellings, same meaning, same word.
Identity composes
A parent's BlueId is computed from its own fields plus the BlueIds of its children — not by flattening the universe into one byte string. So when one order's status changes:
Agreement A Agreement A'
├── customer (unchanged) ├── customer (same BlueId)
├── flowers (unchanged) ├── flowers (same BlueId)
├── dinner (changed) ├── dinner' (new BlueId)
└── payment (unchanged) └── payment (same BlueId)
Only the changed path gets new identity. Every unchanged subtree keeps its BlueId — which is why snapshots, deduplication, caching, and change detection come essentially for free.
One caution: a BlueId proves what was said, exactly. It does not prove the statement is true, the author was authorized, or the event happened. Those proofs come from Timelines and Mandates — which is precisely why they exist.