Skip to main content

The Blue Directive

While Blue enforces a rigorous structure internally, it aims to be as user-friendly as possible for document authors. The blue directive bridges this gap by transforming human-friendly documents into proper Blue documents before processing begins.

Preprocessing with the Blue Directive​

The blue directive appears at the root level of a document and specifies transformations to apply during preprocessing:

blue: Ticket Details v1.0
Ticket Number: ABC-12345
Departure Date: 2023-10-15
Seat: 14A

Preprocessing occurs before any other document processing, including BlueId calculation. This ensures that:

  1. The original document can be user-friendly and flexible
  2. The resulting document strictly follows Blue conventions
  3. The BlueId is calculated only after preprocessing completes

The blue directive itself is removed during preprocessing, meaning it doesn't affect the document's BlueId or semantic content.

Common Transformations​

Let's explore the most useful transformations that can be included in the blue directive:

Replace Inline Types with BlueIds​

This transformation converts simple type names to their full BlueId references:

blue:
  - type:
      blueId: 27B7fuxQCS1VAptiCPc2RMkKoutP5qxkh3uDxZ7dr6Eo
    mappings:
      Person: 8xYi5Svou5DVawB7CDEGuZitUGFChRYcJUF67bQ3NfXt
      Dog: G1pcQx2tq16z5yVqE9TGaCH5uCDAaMZ6uFts7d3NztYo

name: Alice Smith
type: Person
pet:
  type: Dog
  name: Rex

After preprocessing:

name: Alice Smith
type:
  blueId: 8xYi5Svou5DVawB7CDEGuZitUGFChRYcJUF67bQ3NfXt
pet:
  type:
    blueId: G1pcQx2tq16z5yVqE9TGaCH5uCDAaMZ6uFts7d3NztYo
  name: Rex

This transformation (BlueId: 27B7fuxQCS1VAptiCPc2RMkKoutP5qxkh3uDxZ7dr6Eo) allows you to write documents with simple type names that humans can understand.

Infer Basic Types For Untyped Values​

This transformation automatically determines types for primitive values:

blue:
  - type:
      blueId: FGYuTXwaoSKfZmpTysLTLsb8WzSqf43384rKZDkXhxD4

x: 12
y: true
z: Hello

After preprocessing:

x:
  type: Integer
  value: 12
y:
  type: Boolean
  value: true
z:
  type: Text
  value: Hello

This transformation (BlueId: FGYuTXwaoSKfZmpTysLTLsb8WzSqf43384rKZDkXhxD4) eliminates the need to explicitly specify types for every value.

Convert Attribute Names To Camel Case​

This transformation standardizes field names to programming-friendly format:

blue:
  - type:
      blueId: GpMaofZmtLhEQbwkaYd3hm6Es1udEySM6svg8UoN1yEH

Seat No.: 156
Arrival Time: 15:25

After preprocessing:

seatNo: 156
arrivalTime: 15:25

This transformation (BlueId: GpMaofZmtLhEQbwkaYd3hm6Es1udEySM6svg8UoN1yEH) makes documents both human-readable and programming-friendly.

Normalize DateTime Values​

This transformation converts date strings to structured DateTime objects:

blue:
  - type:
      blueId: 93nhEGAmviA5Ey8wZ4ZfeHheAbzvxz473rG92zznvTps
    datetimePattern: yyyy-MM-dd HH:mm

arrival: 2025-03-27 15:25

After preprocessing:

arrival:
  type: DateTime
  year: 2025
  month: 3
  day: 27
  hour: 15
  minute: 25

This transformation (BlueId: 93nhEGAmviA5Ey8wZ4ZfeHheAbzvxz473rG92zznvTps) allows human-readable dates while ensuring proper structural representation.

Map Attribute Names​

This transformation translates field names between languages or formats:

blue:
  - type:
      blueId: 27B7fuxQCS1VAptiCPc2RMkKoutP5qxkh3uDxZ7dr6Eo
    mappings:
      チケット整理番号: ticketSerial
      出発日時: departure
      座席番号: seatNo

チケット整理番号: HL-923554
出発日時: 2025-03-27 15:25
座席番号: 15

After preprocessing:

ticketSerial: HL-923554
departure: 2025-03-27 15:25
seatNo: 15

This enables content creation in any language while maintaining consistent field names in the processed document.

Default Blue Directive​

Every Blue document has an implicit default blue directive if none is specified:

blue:
  - type:
      blueId: 27B7fuxQCS1VAptiCPc2RMkKoutP5qxkh3uDxZ7dr6Eo
    mappings:
      Text: F92yo19rCcbBoBSpUA5LRxpfDejJDAaP1PRxxbWAraVP
      Double: 68ryJtnmui4j5rCZWUnkZ3DChtmEb7Z9F8atn1mBSM3L
      Integer: DHmxTkFbXePZHCHCYmQr2dSzcNLcryFVjXVHkdQrrZr8
      Boolean: EL6AjrbJsxTWRTPzY8WR8Y2zAMXRbydQj83PcZwuAHbo
      List: G8wmfjEqugPEEXByMYWJXiEdbLToPRWNQEekNxrxfQWB
      Dictionary: 294NBTj2mFRL3RB4kDRUSckwGg7Kzj6T8CTAFeR1kcSA
  - type:
      blueId: FGYuTXwaoSKfZmpTysLTLsb8WzSqf43384rKZDkXhxD4

This default directive (BlueId: EWj6aMM5nRAS9hYmrJXpJeL6zNRCVtZJguan9b4ZqJN7) provides mappings for basic types and enables type inference.

A Complete Example​

Let's see what happens when we apply multiple transformations together:

blue: Ticket Details v.1.51
Ticket Serial No.: HL-923554
Departure: 2025-03-27 15:25
Seat No.: 15

After all transformations:

ticketSerial:
  type:
    blueId: F92yo19rCcbBoBSpUA5LRxpfDejJDAaP1PRxxbWAraVP
  value: HL-923554
departure:
  type:
    blueId: 4UevQMiUg5BjYe9sX26xf4QHgFoKPmf7JVAM9wk4bmzR
  year:
    type:
      blueId: DHmxTkFbXePZHCHCYmQr2dSzcNLcryFVjXVHkdQrrZr8
    value: 2025
  month:
    type:
      blueId: DHmxTkFbXePZHCHCYmQr2dSzcNLcryFVjXVHkdQrrZr8
    value: 3
  day:
    type:
      blueId: DHmxTkFbXePZHCHCYmQr2dSzcNLcryFVjXVHkdQrrZr8
    value: 27
  hour:
    type:
      blueId: DHmxTkFbXePZHCHCYmQr2dSzcNLcryFVjXVHkdQrrZr8
    value: 15
  minute:
    type:
      blueId: DHmxTkFbXePZHCHCYmQr2dSzcNLcryFVjXVHkdQrrZr8
    value: 25
seatNo:
  type:
    blueId: DHmxTkFbXePZHCHCYmQr2dSzcNLcryFVjXVHkdQrrZr8
  value: 15

The BlueId of this fully processed document is 2YUzCvdTQKB34MutfhsKHEEbdNqJL6FVPNvNcVVvBJDP.

The Power of Text Aliases​

One of the most powerful aspects of the Blue directive is the ability to use text aliases for transformation sets:

blue: Ticket Details v.1.51
Ticket Serial No.: HL-923554
Departure: 2025-03-27 15:25
Seat No.: 15
blue: Ticket Details v.1.51 JP
チケット整理番号: HL-923554
出発日時: 2025-03-27 15:25
座席番号: 15

Despite being written in different languages, both documents preprocess to identical structures with the same BlueId: 2YUzCvdTQKB34MutfhsKHEEbdNqJL6FVPNvNcVVvBJDP.

To make this work, you register aliases with your Blue processor:

blue.addPreprocessingAliases(Map.of(
        "Ticket Details v.1.51", "5VEx7ee9to3Z56eVdkNzBfpHaZU9KD4moYttpS5h6bHt",
                                     "Ticket Details v.1.51 JP", "3wfkqtvZvgiff55ZhrtToK3sDcPHvKKY5DcZw68nor3i"
));

URL References and Security​

The blue directive can also reference a URL:

blue: https://language.blue/simple.blue
name: Alice
type: Person
age: 25

For security reasons, URL fetching is disabled by default in most Blue processors. To enable it:

blue.enablePreprocessingDirectivesFetchForUrls();
caution

Enabling URL fetching creates potential security vulnerabilities. Use registered aliases in production systems.

Creating Custom Transformations​

Anyone can define custom transformations for specialized preprocessing needs. These transformations must be registered with processors that need to understand them.

Next Steps​

Now that you understand how the blue directive enables flexible document authoring while maintaining strict typing, let's explore the formal specification for a complete reference.