Blue directive

The blue directive is an authoring-only instruction that runs before a source document becomes identity-bearing Blue content.

It lets a document start in a human-friendly form, apply deterministic preprocessing, and then remove the directive before BlueId calculation. The blue field itself is not part of the final semantic document.

§What it does

Preprocessing happens before ordinary document processing and before content BlueId calculation.

That means a source document can use readable aliases, compact scalar values, or a named preprocessing environment, while the resulting Blue document still has explicit types and canonical structure.

1blue:
2  - type:
3      blueId: 27B7fuxQCS1VAptiCPc2RMkKoutP5qxkh3uDxZ7dr6Eo
4    mappings:
5      Person: 8xYi5Svou5DVawB7CDEGuZitUGFChRYcJUF67bQ3NfXt
6
7name: Alice Smith
8type: Person

After preprocessing, the directive is removed and the type alias is replaced with a BlueId reference:

1name: Alice Smith
2type:
3  blueId: 8xYi5Svou5DVawB7CDEGuZitUGFChRYcJUF67bQ3NfXt

§Supported standard transforms

The current Java implementation recognizes these standard preprocessing transforms:

The implementation also accepts legacy transform BlueIds for compatibility, but new source documents should use the current BlueIds above.

§Default preprocessing

If a source document does not provide a blue directive, Blue still applies the default preprocessing environment. This gives common type names their current canonical BlueIds and infers primitive scalar types.

The current default type aliases include:

§Type alias replacement

Use Replace Inline Types with BlueIds when a source document should use short type names but still produce portable Blue content.

1blue:
2  - type:
3      blueId: 27B7fuxQCS1VAptiCPc2RMkKoutP5qxkh3uDxZ7dr6Eo
4    mappings:
5      Ticket: 7LqH6sGz5HEf4DN6bn4oHRN2u4A93cRQxk4cTEu7zHmq
6
7type: Ticket
8ticketNumber: ABC-12345

After preprocessing:

1type:
2  blueId: 7LqH6sGz5HEf4DN6bn4oHRN2u4A93cRQxk4cTEu7zHmq
3ticketNumber: ABC-12345

§Basic type inference

Use Infer Basic Types For Untyped Values when primitive scalar values should be expanded into typed Blue values.

1blue:
2  - type:
3      blueId: FGYuTXwaoSKfZmpTysLTLsb8WzSqf43384rKZDkXhxD4
4
5quantity: 12
6confirmed: true
7note: Ready

After preprocessing:

1quantity:
2  type:
3    blueId: E2LM6qgzWG9ttagq2xTmiZkgYEAgkYedFCmU9v7NnVEq
4  value: 12
5confirmed:
6  type:
7    blueId: AwvXD961fmnmqcSQhjMA7r15HpVh39cefb6ZTyUz2Fm2
8  value: true
9note:
10  type:
11    blueId: GX7CFUmSDrE2MzptunLCCdZwnuwwrenRQqEnHL4x3uoC
12  value: Ready

§String aliases

The Java API can also map a string-valued blue directive to a preprocessing environment configured by the host application.

1blue: Ticket Details v1
2Ticket Number: ABC-12345
3Seat: 14A

In that form, Ticket Details v1 is not magic syntax. It is an alias registered by the environment before preprocessing. The alias resolves to a BlueId for the preprocessing content to apply.

§Identity rule

A source document that contains blue is not final BlueId input. It must be preprocessed first.

The safe flow is:

1. Parse the source document.
2. Apply default preprocessing and any declared transforms.
3. Remove the blue directive.
4. Calculate the content BlueId from the preprocessed document.

This keeps authoring conveniences out of the final identity while still letting them shape the canonical content deterministically.