Skip to main content

Blue Language

Blue Language is a simple, YAML or JSON-based language that supports inheritance and content-addressable identifiers. Any YAML or JSON document is a valid Blue document, provided it respects certain attribute conventions.

Introduction​

Blue Language is designed to facilitate the creation of structured, inheritable data definitions using a YAML or JSON syntax. Its special features include:

  • Type Inheritance: Allowing documents to inherit properties and constraints from other documents.
  • Content Hashing: Assigning a unique blueId to each document based on its content, enabling documents to be interconnected, creating a web of linked documents.

By leveraging these features, Blue enables the creation of complex data structures that are both reusable and traceable.

Key Features​

Type Inheritance​

  • Inheritance Mechanism: Blue allows documents to inherit attributes and constraints from other documents by specifying a type.
  • Subtype Relationships: If document B specifies type: A, then B is considered a subtype of A, inheriting its properties.

Content Hashing and BlueId​

  • BlueId: A blueId is a content hash calculated for every document. It uniquely identifies the document based on its content.
  • Interconnected Documents: The hashing mechanism ensures that documents can reference each other unambiguously, creating a web of interconnected documents.
  • Content Addressability: Any change in the document content results in a new blueId, ensuring integrity and traceability.

Base Structure​

Every node in Blue is of a base type. If a node does not specify a type, it defaults to this base type.

Essential Attributes​

  • name: The name of the element.
  • description: A textual description of the element.
  • type: The type of the element, which can be a basic type or another named document.
  • constraints: Constraints that apply to the element.
  • value: The value of the element, used for basic types.
  • items: A list of elements, used when defining lists.

Note: The attributes name, description, type, constraints, value, and items have special meanings and must be used according to their descriptions. Do not overwrite these attributes with custom definitions.

Basic Types​

Blue provides several basic types:

  • Text: Represents textual data.
  • Integer: Represents integer numbers.
  • Number: Represents numeric values, including decimals.
  • Boolean: Represents boolean values (true or false).

Examples​

Defining a Base Pet Type​

# YAML
name: Pet
description: A base type for all pets.
age:
  description: The age of the pet in years.
  type: Integer
  constraints:
    minimum: 0

Defining a Dog Type Inheriting from Pet​

# YAML
name: Dog
type: Pet
breed:
  description: The breed of the dog.
  type: Text
  constraints:
    required: true
isTrained:
  description: Indicates if the dog is trained.
  type: Boolean

Creating a Subtype with Additional Properties​

# YAML
name: Pirat
type: Dog
breed: German Shepherd
isTrained: false

Defining Currency Type​

# YAML
name: Currency
abstract: true
type: Text
constraints:
  allowedValues:
    - EUR
    - USD
    - PLN

Defining Positive Number Type​

# YAML
name: Positive Number
abstract: true
type: Number
constraints:
  exclusiveMinimum: 0

Defining Payment Value Type​

# YAML
name: Payment Value
abstract: true
amount:
  type: Positive Number
currency:
  type: Currency

Operations​

Resolving Nodes​

Resolving a node involves expanding all fields from its subtypes and inherited documents, resulting in a fully detailed node.

Example:

# Define A
name: A
x: 10
y:
  type: Integer
---
# Define B Inheriting from A
name: B
type: A
y: 5
z: 5

# After resolving B, it will have:
# - x: 10 (inherited from A)
# - y: 5 (overridden)
# - z: 5 (additional property)

Reversing Nodes​

Reversing a node reduces it to its minimal form by removing inherited properties that match defaults from parent types.

Example:

# Resolved Node B
name: B
type: A
x: 10
y: 5
z: 5
---
# After reversing, Node B simplifies to:
name: B
type: A
y: 5
z: 5

Extending Nodes​

Extending a node populates it with additional information from its referenced types or blueIds without fully resolving all inherited properties.

Example:

# Node Y with Reference to A
name: Y
forA:
  blueId: blueId-A

# After extension, 'forA' will include properties from A.

BlueId Calculation​

BlueId is a content hash calculated for every document using a bottom-up approach, starting from the deepest layer and propagating upwards. 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.

This documentation provides an overview of the Blue Language, highlighting its key features—type inheritance and content hashing—and explaining how they enable the creation of interconnected, reusable data structures.

Feel free to explore the examples and experiment with creating your own documents using YAML or JSON formats, adhering to the attribute conventions described.

Remember, any YAML or JSON document is a valid Blue document as long as the required attributes are respected.