What is Blue?

Most software teams repeatedly define the same concepts in slightly different places. One service has a Person class. Another service has a Customer DTO. A front-end package has a TypeScript interface. A data warehouse has a table. A partner API has a JSON schema. The names are familiar, but the definitions drift: one system calls the field surname, another calls it lastName, one stores money as a decimal, another stores minor units, one treats a status as free text, another treats it as an enum.

Blue starts from a simple question: what if the important definitions were documents with stable identity, and those documents could be reused across systems without a central registry deciding every future use case?

A Blue document can describe ordinary data. It can also describe the type of other data. It can reference other content by BlueId. It can carry contracts that define how timeline evidence changes its state. It can include deterministic BEX logic that returns patches and events. The result is not just another serialization format. It is a way to represent meaning, identity, and process in the same document graph.

§Blue in one example

Start with a small type. This is a Blue document that describes a money amount stored in minor units:

1name: Money Amount
2amountMinor:
3  type: Integer
4  schema:
5    minimum: 0
6currency:
7  type: Text
8  schema:
9    minLength: 3
10    maxLength: 3

Now define a person-like record that uses it:

1name: Person
2fullName:
3  type: Text
4age:
5  type: Integer
6spent:
7  type:
8    blueId: <MoneyAmountBlueId>

The important part is not the exact field names. The important part is that Money Amount and Person are themselves content. They can be hashed. They can be referenced. They can be expanded when needed. They can be used by Java code, a web app, a workflow document, or a partner integration without copying the definition into every codebase.

An instance can then point to the type:

1name: Alice
2fullName: Alice Smith
3type:
4  blueId: <PersonBlueId>
5age: 25
6spent:
7  amountMinor: 2715
8  currency: USD

A receiver that already knows <PersonBlueId> does not need the full type definition inline. A receiver that does not know it can ask a node provider for that BlueId and verify that the returned content is the content it requested.

This is the first Blue idea: references can point to content, not just locations.

§Blue is content-addressed

A traditional identifier usually tells you where to look or what row to load. A URL points to a server path. A database id points to a row in one database. A UUID tells you that something was assigned an id, but it does not tell you what the thing means.

A BlueId is different. It is derived from Blue content. If the content changes, the identity changes. If two authored forms preprocess, resolve, and canonicalize to the same meaning, they can have the same content identity even if the source YAML was written differently.

That distinction matters in integrations. A partner does not need to trust that your string label Person means the same thing as their string label Person. They can compare the actual BlueId of the type being used. A document does not need to embed a full product catalog every time it references a product. It can include a pure reference:

1product:
2  blueId: <ProductBlueId>

Pure means pure: a { blueId: ... } reference is the entire node. It is not a reference plus extra local fields. If you want a typed value with fields, write the BlueId under type:

1product:
2  type:
3    blueId: <ProductTypeBlueId>
4  sku: WEEKEND-2P
5  title: Weekend for two

That rule keeps identity unambiguous. A node is either a pure reference to known content or it is local content that may itself be typed by a reference.

§Blue is typed without separating “schema files” from “data files”

In Blue, a type is a Blue node. There is no hard wall between a schema language and an instance language. A document can be a type for another document. A more specific type can extend a general one. A business object can point at a shared type and add local fields.

For example, a general product type can require a SKU and price:

1name: Product
2sku:
3  type: Text
4  schema:
5    required: true
6    minLength: 3
7price:
8  amountMinor:
9    type: Integer
10    schema:
11      minimum: 0
12  currency:
13    type: Text
14    schema:
15      minLength: 3
16      maxLength: 3

A package offer can extend that product shape:

1name: Package Offer
2type: Product
3offerKind: package
4seller:
5  name:
6    type: Text
7included:
8  hotel:
9    title:
10      type: Text
11  restaurant:
12    title:
13      type: Text

The extension model is additive and compatibility-preserving. If a parent fixes a value, a child cannot silently replace it with a different value. If a parent says a field is an integer, a child cannot turn it into arbitrary text. If a parent contributes a schema constraint, a child can add compatible constraints but cannot weaken the inherited meaning.

This is what lets Blue types evolve like a language instead of a pile of incompatible DTOs.

§Blue separates source convenience from identity

Humans like concise source. Machines need deterministic structure. Blue handles that through preprocessing.

A source document can use core type aliases such as Text, Integer, Double, Boolean, Dictionary, and List. It can declare document-local imports through the root blue directive. It can write scalar values directly instead of wrapping everything by hand. During preprocessing, those conveniences are converted into the strict node model used for resolution and identity.

For example:

1blue:
2  imports:
3    Person:
4      blueId: <PersonBlueId>
5
6name: Alice
7type: Person
8age: 25

After preprocessing, Person in a type position becomes a pure BlueId reference, the integer scalar is understood as an integer value, and the blue directive is removed. The directive helped the author, but it is not part of the resulting identity-bearing content.

This gives Blue a practical authoring story without making identity depend on hidden local editor settings.

§Blue documents can process timeline evidence

Typed content and identity are only the first half of Blue. The other half is deterministic processing.

A processable Blue document can contain contracts. In the Coordination package, those contracts can include timeline channels, operations, sequential workflows, Compute steps, embedded node channels, and checkpoints. When a timeline entry or lifecycle event is delivered, the processor evaluates the document contracts and returns a deterministic result.

The result is a new document, emitted events, gas accounting, and metadata such as checkpoints.

1current document
2+ delivered entry
3+ channels
4+ operations
5+ workflows
6+ BEX Compute steps
7= new document + emitted events + gas + checkpoints

The simplest useful example is Counter. It has one state field and one operation:

1name: Counter
2counter: 0
3contracts:
4  ownerChannel:
5    type: Coordination/Timeline Channel
6    timelineId: counter-demo
7
8  increment:
9    type: Coordination/Operation
10    channel: ownerChannel
11    request:
12      amount:
13        type: Integer

When an increment request is delivered on the right channel, a workflow can run a BEX Compute step. The BEX reads /counter, reads the request amount, appends a patch to replace /counter, appends an event, and returns both collections. The processor applies the returned changes and records a checkpoint so the same delivered entry does not increment twice.

Counter is small, but it is not a toy in the architectural sense. It contains the full loop.

§Blue can model real business processes

The flagship example in these docs is a weekend package checkout. It models an offer from ITC / mega-pakiety.pl for a romantic weekend package that includes a hotel stay and a restaurant dinner. A customer payment is secured first. Then the reseller attaches or creates the hotel and restaurant orders. The PayNote requests completion only after both merchant confirmations arrive. Finally, the parent package order becomes ready_to_use.

That flow matters because it is not just “change status from A to B.” It has separate participants, child documents, ordering requirements, duplicate-delivery concerns, and payment safety rules.

The Blue document can show:

• the offer content that the customer saw;
• the order template used to start a package order;
• the payment state of the package order;
• the embedded PayNote that governs the customer payment;
• the embedded hotel and restaurant order snapshots;
• the workflows that attach payment tokens, attach PayNotes, attach component orders, react to child events, and mark the package ready;
• the BEX guards that make repeated or invalid entries safe;
• the final condition that both merchant orders must be confirmed before payment completion is requested.

Blue does not perform the card authorization by itself. It does not book the hotel by itself. It does not magically trust a merchant. Those are host-system responsibilities. Blue represents the document state and deterministic workflow logic around those responsibilities.

§What Blue is not

Blue is not a database. A database can store Blue documents, indexes, snapshots, timeline entries, and provider state, but Blue does not prescribe your database.

Blue is not a blockchain. A timeline can be append-only and hash-linked, and document states have content identity, but Blue does not require global consensus or tokens.

Blue is not a payment processor. PayNote is a transaction-governance document. It can record requests, responses, secured funds, completion, cancellation, and reversal states. The actual payment rail is still outside the deterministic document processor.

Blue is not JavaScript embedded in YAML. Current implementation-facing examples use BEX: deterministic Blue-data programs with explicit operators such as $document, $event, $appendChange, and $appendEvent.

Blue is not just YAML. YAML is an authoring syntax. The meaningful layer is the Blue node model after preprocessing, resolution, canonicalization, and processing.

§The mental model to keep

Use this model as you read the rest of the docs:

1Blue Language
2  defines documents, nodes, types, preprocessing, schema, lists, canonical identity, and BlueId
3
4Contracts and Processor
5  defines deterministic document processing: channels, handlers, events, scopes, lifecycle, gas, and checkpoints
6
7Coordination
8  defines timeline-driven operations and workflows used by the examples
9
10BEX
11  defines deterministic document-owned logic encoded as Blue data
12
13PayNote
14  defines a transaction-governance document model used by the weekend package example

The docs teach these layers through two examples. Counter shows the complete loop with no business noise. Weekend package checkout shows why the loop matters.