Concepts·BlueId essentials

Concepts

BlueId essentials

A BlueId is the canonical, content-derived identifier for a Blue node. It is how documents, types, and timeline entries refer to meaning rather than to a place.

What a BlueId is

Every Blue node — a document, a type, a fragment, a timeline entry, a referenced object — has a stable identifier derived from its content using a canonical Base58-SHA256 scheme. That identifier is its BlueId.

  • If the content does not change, the BlueId does not change.
  • If the content changes — even a single field — the BlueId changes.
  • Two semantically equivalent forms (expanded vs. referenced, key order, harmless formatting) produce the same BlueId after normalization.
A BlueId is what you get when you ask: what is this content, exactly?

Why this matters

Most identifiers in software are addresses — they tell you where something lives. A BlueId tells you what something is. That is a much stronger guarantee for an interaction protocol because:

  • Two participants can agree they are looking at the same document without trusting any single host.
  • Types can be referenced from anywhere and still mean the same thing.
  • Timeline entries can be hash-linked into a tamper-evident chain via prevEntry.blueId.
  • Caches and indexes can deduplicate trivially.

A small example

These two YAML fragments describe the same content. After normalization, they share the same BlueId:

yaml
type: Common/Record
name: Demo Counter
counter: 0
yaml
name: Demo Counter
counter: 0
type: Common/Record

Change counter: 0 to counter: 1, and the BlueId changes. That is how the document stepper knows a step actually happened: the document's BlueId before processing differs from the BlueId after processing, and the difference is exactly the diff you see on screen.

BlueIds in the protocol

  • Types. Every type referenced from repo.blue resolves to a BlueId. Conversation/Operation Request means a specific blueId, not just a string.
  • References. A document can reference another node by its BlueId without copying it. The reference is stable forever.
  • Timeline entries. Each new entry sets prevEntry.blueId to the BlueId of the previous entry, forming a chain.
  • Pinned operations. A Conversation/Operation Request may pin a target document by BlueId, so the operation only applies if the document has not drifted.

Where you see BlueIds in this site

The document stepper shows BlueIds in three places:

  • The current document BlueId, recomputed after every step.
  • Every timeline entry's BlueId, used as the prevEntry.blueId of the next entry on the same channel.
  • An epoch's before and after document BlueIds — visible proof that the state moved.
A BlueId is derived from content. If the content changes, the BlueId changes. That single property is what makes Blue references portable, references stable, and timelines tamper-evident.

Going deeper

The deeper mechanics — canonicalization rules, expansion vs. reference, the exact hash construction — live in the Language track tutorial and in the specification. Most readers do not need that level of detail. The properties on this page are enough for everyday use.