Introduction to Blue Language

The Problem of Reinvention

How many times have you defined a Person class in your career?

// Java
public class Person {
    private String name;
    private String surname;
    private int age;
    // And so on...
}

// TypeScript
interface Person {
    name: string;
    surname: string;
    age: number;
    // And so on...
}

# Python
class Person:
    def __init__(self, name, surname, age):
        self.name = name
        self.surname = surname
        self.age = age
        # And so on...

Every API, every service, every application reinvents these basic types. We have schemas, DTOs, POJOs, models, and interfaces—all representing the same concepts in slightly different ways.

Solutions like Schema.org tried to standardize these definitions, but they weren't flexible enough or easy enough to integrate with existing systems. The problem persists: we lack a universal language for describing digital objects.

A Universal Language for Digital Objects

We believe that clear communication requires a common language—not just for simple API requests and responses, but for complex digital relationships, contracts, and behaviors. That's why Blue is the Basic Language that Unifies Experience.

Blue lets you define an object once and use it everywhere, across systems, programming languages, and organizations.

The Core Idea: Content-Addressable Types

The key innovation in Blue is that every document has a unique content hash called a blueId. This is essentially a single word that uniquely represents specific content.

You can try it yourself at web.blue/blue-id-calculator

Let's start with a simple type definition:

name: Simple Amount
amount:
  type: Double
currency:
  type: Text

This has the blueId FgHZjSNb8X9zty82ps4eRkVVuhpPG6ajSGvG6HKKrhUq - a unique fingerprint of its content.

Now we can define another type that uses this one:

name: Person
age:
  type: Integer
spent:
  type:
    blueId: FgHZjSNb8X9zty82ps4eRkVVuhpPG6ajSGvG6HKKrhUq # Simple Amount

This Person type has blueId GRwTYsr32pieyWQH1PAFrQAWBUCbKivH4K9yYC8hFHaU.

Creating Instances with Types

Now we can create an actual person:

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

This instance has blueId 3JTd8soWugBAfxBAYKuScmmvbdgFw9SVp7fPdJgrAUVn.

The Magic of Meaning-Based Identity

Here's where it gets interesting. You'll get the exact same blueId if you expand all the type references:

name: Alice
type:
  name: Person
  age:
    type: Integer
  spent:
    type:
      name: Simple Amount
      amount:
        type: Double
      currency:
        type: Text
age: 25
spent:
  amount: 27.15
  currency: USD

This produces the same blueId: 3JTd8soWugBAfxBAYKuScmmvbdgFw9SVp7fPdJgrAUVn

This is a core principle of Blue: documents with the same meaning have the same blueId, regardless of how they're represented.

Simplifying with Names

For convenience, you can use type names directly with the blue directive:

blue: https://language.blue/simple.blue
name: Alice
type: Person
age: 25
spent:
  amount: 27.15
  currency: USD

This tells processors where to find the type definitions. Throughout this documentation, we'll use this convention to keep examples clean and focused.

Extension and Type Safety

In Blue, every document can be a type for another document:

name: Alice Extended
type: Alice
smiling: true
friends:
  type: List
  itemType: Person

Every Alice Extended must be an Alice. If fields like age or spent were already set in Alice, they cannot be overwritten—you can only add new attributes or complete those that weren't specified earlier.

This creates a strong type system without requiring a centralized registry of types.

Language Integration

Blue isn't just a document format—it integrates with your programming language of choice. For Java:

@TypeBlueId("FgHZjSNb8X9zty82ps4eRkVVuhpPG6ajSGvG6HKKrhUq")
@AllArgsConstructor
public class SimpleAmount {
    Double amount;
    String currency;
}

@TypeBlueId("GRwTYsr32pieyWQH1PAFrQAWBUCbKivH4K9yYC8hFHaU")
@AllArgsConstructor
public class Person {
    String name;
    Integer age;
    SimpleAmount spent;
}

// Creating and using a Blue document
Person alice = new Person("Alice", 25, new SimpleAmount(27.15, "USD"));
Blue blue = new Blue();

// Calculate the blueId
String blueId = blue.calculateBlueId(alice);
assert blueId.equals("3JTd8soWugBAfxBAYKuScmmvbdgFw9SVp7fPdJgrAUVn");

// Convert to YAML
String yaml = blue.objectToYaml(alice);

The calculated blueId will match the one from our YAML examples, and the generated YAML will be semantically equivalent.

Reusing Existing Types

Rather than defining all types yourself, you can import libraries from repo.blue and other sources. This gives you immediate access to standard types like Person, Address, Payment, and more specialized industry-specific types.

For popular types, language-specific libraries are available:

# JavaScript/TypeScript
npm install @blue-repository/identity-types

# Java
<dependency>
  <groupId>blue.repository</groupId>
  <artifactId>identity-types</artifactId>
  <version>1.0.0</version>
</dependency>

# Python
pip install blue-repository-identity-types

This eliminates the need to reinvent common structures and ensures consistent definitions across systems and organizations.