BlueId: Universal Content Addressing

In previous sections, we explored Blue's type system and document inheritance. Now, let's focus on the heart of Blue's referencing system: the BlueId—a unique identifier based on content rather than location.

Beyond Traditional Identifiers

Traditional identifiers tell you where to find something:

• URLs point to server locations
• Database IDs reference rows in tables
• UUIDs are assigned to specific objects

In contrast, a BlueId represents what something is—its actual content and meaning. This creates a fundamentally different way of referencing digital objects:

# Traditional approach
  {
    "id": "8f7d3c2e-1a5b-4f9c-8d7e-6b2c1a3f4e5d",
    "name": "iPhone 14",
    "price": 799.99
  }

# Blue approach
name: iPhone 14
price: 799.99
# This document's BlueId is HxvqaVPopn9w8CuVAp4YpVbiaEG25MmZY1UVZ4nA1hxV

The BlueId is not stored in the document—it's derived from the content itself.

The Web of Meaning

Every BlueId represents a "word" in a vast language of digital content:

• Each document node has its own BlueId
• The same content always has the same BlueId
• BlueIds can reference content across systems and organizations
• Multiple documents can incorporate the same content via BlueId

This creates a web of interconnected content where references are based on meaning, not location:

Traditional integration approaches require us to constantly reinvent and redefine our data models. It's like meeting new people and having to teach them the words for "apple," "orange," and "dog" every time. Blue offers a different approach—a shared semantic web where concepts are universally addressable.

Instead of trading isolated schemas and models, we're building a collective knowledge network. Any system can reference any node in this web without prior coordination. Your "Person" type can be immediately understood and used by others without custom mapping or translation.

This network is continuously enriched as more systems adopt Blue. Common patterns naturally emerge, and specialized domains can extend standard types without breaking compatibility. It's a living language that grows organically with use.

BlueId Calculation

BlueId is a content hash calculated for every document using a bottom-up approach, starting from the deepest layer and propagating upwards. Technically, it's a base58-encoded SHA-256 hash of canonicalized JSON (following RFC8785 standards) for each node in the document. This ensures:

• Uniqueness: Any change in the content results in a new BlueId
• Integrity: Documents reference each other unambiguously
• Interconnectedness: Documents can be linked, forming a web of interconnected content

The specific normalization procedures and implementation details are available in the Specification: BlueId Calculation section.

Walking the Blue Web

One of Blue's powerful capabilities is exploring this semantic web by retrieving referenced content as needed. Starting with any BlueId, you can "extend" outward to explore connected nodes.

For example, with our "Alice" document from earlier:

# Starting point - just the BlueId
blueId: 9UpJ6SdjhX7MFXBKywH5ps5npUWAX76YnEDakrjPJ9LU

We can extend one level to see the immediate properties:

Node node = blue.blueIdToNode("9UpJ6SdjhX7MFXBKywH5ps5npUWAX76YnEDakrjPJ9LU");
Node oneLevelExtended = blue.extend(node, PathLimits.withSinglePath("/*"));

Which produces:

name: Alice
type:
  blueId: 6E93TBwTYYZ3zaWQhryCWz4rnJgGisaDgPrU8RnVLWuC # Person
age: 25
spent:
  blueId: HB8H2fLKAVZcEcqh19HiTehXjy25d22MMF6wAVvDzC4i # 27.15 USD

We can explore specific paths more deeply:

Node spentExtended = blue.extend(node, PathLimits.withSinglePath("/spent/*"));

name: Alice
type:
  blueId: 6E93TBwTYYZ3zaWQhryCWz4rnJgGisaDgPrU8RnVLWuC # Person
age: 25
spent:
  amount: 27.15
  currency: USD

Practical Example: E-Commerce System

Let's explore a more complex real-world example showing how BlueIds connect multiple documents in an e-commerce system:

# Customer order with BlueId references
name: Order #12345
date: 2023-06-15
customer:
  blueId: 9UpJ6SdjhX7MFXBKywH5ps5npUWAX76YnEDakrjPJ9LU # Alice
items:
  - product:
      blueId: HxvqaVPopn9w8CuVAp4YpVbiaEG25MmZY1UVZ4nA1hxV # iPhone 14
    quantity: 1
  - product:
      blueId: 8xYi5Svou5DVawB7CDEGuZitUGFChRYcJUF67bQ3NfXt # Wireless Earbuds
    quantity: 2
catalog:
  blueId: kL9mN0pQrStUvWxYz1A2B3C4D5E6F7G8H4FGh7j8 # Full product catalog

In this example, the order references:

• A customer profile (Alice)
• Individual products being ordered
• The entire product catalog (potentially thousands of products)

The order document remains lightweight because it only contains BlueId references to these larger entities. If we need customer details, we can extend just that path:

Node orderWithCustomer = blue.extend(order, PathLimits.withSinglePath("/customer/**"));

name: Order #12345
date: 2023-06-15
customer:
  name: Alice
  type:
    name: Person
    # Full Person type definition
  age: 25
  spent:
    amount: 27.15
    currency: USD
items:
  - product:
      blueId: HxvqaVPopn9w8CuVAp4YpVbiaEG25MmZY1UVZ4nA1hxV # iPhone 14
    quantity: 1
  - product:
      blueId: 8xYi5Svou5DVawB7CDEGuZitUGFChRYcJUF67bQ3NfXt # Wireless Earbuds
    quantity: 2
catalog:
  blueId: kL9mN0pQrStUvWxYz1A2B3C4D5E6F7G8H4FGh7j8 # Full product catalog

Extension Risk Management

Extend carefully! Some BlueIds can represent enormous amounts of data:

• The catalog BlueId in our example might contain thousands of products, each with detailed specifications
• A BlueId representing Wikipedia would contain millions of interconnected articles
• A Timeline of an active user could contain years of activity records

As in real life, you rarely need to download all knowledge—just the parts relevant to your current task. Blue's extension mechanism lets you precisely control how much data you retrieve.

web.blue: The Blue Explorer

Web.blue is a website that helps you explore the Blue web. You can provide your own node providers—components that map BlueIds to documents—and visualize content in multiple ways:

As a document:

Or as an interactive graph that you can traverse:

Web.blue demonstrates how BlueIds enable document exploration without prior knowledge of structure. The restaurant menu example loads gradually as content is retrieved from IPFS, showing how Blue documents can be distributed across decentralized storage systems.

This approach solves a fundamental web problem: content disappearing when URLs change. With BlueIds, you have the fingerprint of content, allowing you to retrieve it from any source that has it. The mapping between BlueIds and IPFS Content Identifiers follows specific transformation rules detailed in the Java implementation section.

Why BlueId Matters

The BlueId approach provides several unique advantages:

1. Semantic References: References point to meaning, not just bytes
2. Universal Vocabulary: Every piece of content has a unique "word" that identifies it
3. Location Independence: Content can move between systems while references remain valid
4. Natural Deduplication: Identical content is automatically unified
5. Verifiable Content: BlueIds serve as built-in integrity checks

Compare this with other hash-based systems:

System	What it Hashes	Purpose
BlueId	Semantic structure with meaning preservation	Content-addressing with semantic awareness
Git Hash	File content + metadata	Version control
IPFS CID	Raw bytes	File storage
Blockchain Hash	Transaction data	Transaction verification

The key distinction is that BlueId preserves meaning, not just structure or bytes.