Schema YAML Reference

Complete reference for the schema YAML format used in Cerulion Graph Editor. Schemas define the structure of data that flows through topics.

File Structure

Schema files are YAML files stored in the schemas/ directory. A file can contain one or more schema definitions.

Basic Structure

schemas:
  SchemaName:
    description: Optional description
    fields:
      field_name: field_type
        description: Optional field description

Schema Definition

Schema Name

Format: PascalCase (e.g., TemperatureReading, SensorData)
Uniqueness: Must be unique within a project
Characters: Letters, numbers, underscores
Case sensitive: TemperatureReading ≠ temperatureReading

Description

Optional human-readable description:

schemas:
  TemperatureReading:
    description: "Temperature reading with timestamp from sensor"

Field Types

Primitive Types

Numeric Types

int8 - 8-bit signed integer (-128 to 127)
int16 - 16-bit signed integer (-32,768 to 32,767)
int32 - 32-bit signed integer (-2,147,483,648 to 2,147,483,647)
int64 - 64-bit signed integer
uint8 - 8-bit unsigned integer (0 to 255)
uint16 - 16-bit unsigned integer (0 to 65,535)
uint32 - 32-bit unsigned integer (0 to 4,294,967,295)
uint64 - 64-bit unsigned integer
float32 - 32-bit floating point number
float64 - 64-bit floating point number

Other Primitives

bool - Boolean value (true/false)
string - Variable-length text string
bytes - Raw binary data

Collection Types

Arrays

Fixed or variable-length arrays:

fields:
  array<float32> values:
    description: Array of float values
    length: 10  # Optional: fixed length

Syntax: array<element_type>
Length: Optional fixed length, or variable if omitted
Element type: Any primitive or schema type

Maps

Key-value mappings:

fields:
  map<string, float32> metadata:
    description: String to float mapping

Syntax: map<key_type, value_type>
Key types: string, int32, int64, uint32, uint64
Value type: Any primitive or schema type

Schema References

Reference other schemas as field types:

schemas:
  Point3D:
    fields:
      float32 x:
      float32 y:
      float32 z:

  Pose:
    fields:
      Point3D position:  # Reference to Point3D schema
        description: 3D position
      array<float32> orientation:
        length: 4

Field Definition

Basic Field

fields:
  field_name: field_type

Field with Description

fields:
  field_name: field_type
    description: What this field represents

Field Examples

fields:
  temperature: float32
    description: Temperature in Celsius
  
  timestamp: uint64
    description: Unix timestamp in nanoseconds
  
  sensor_id: string
    description: Unique sensor identifier
  
  is_active: bool
    description: Whether sensor is currently active
  
  readings: array<float32>
    description: Array of sensor readings
    length: 100
  
  metadata: map<string, string>
    description: Key-value metadata pairs

Complete Examples

Simple Schema

schemas:
  TemperatureReading:
    description: Temperature reading from a sensor
    fields:
      float32 temperature:
        description: Temperature in Celsius
      uint64 timestamp:
        description: Unix timestamp in milliseconds

Complex Schema

schemas:
  Point3D:
    description: 3D coordinate point
    fields:
      float32 x:
      float32 y:
      float32 z:

  Quaternion:
    description: Rotation quaternion
    fields:
      float32 x:
      float32 y:
      float32 z:
      float32 w:

  Pose:
    description: Position and orientation
    fields:
      Point3D position:
        description: 3D position
      Quaternion orientation:
        description: Rotation as quaternion

  SensorData:
    description: Complete sensor data package
    fields:
      string sensor_id:
        description: Unique sensor identifier
      Pose pose:
        description: Sensor pose
      array<float32> readings:
        description: Array of sensor readings
        length: 10
      map<string, string> metadata:
        description: Additional metadata
      bool is_calibrated:
        description: Calibration status

Array and Map Examples

schemas:
  ImageData:
    fields:
      uint32 width:
      uint32 height:
      array<uint8> pixels:
        description: Pixel data (width * height * channels)
      
  Configuration:
    fields:
      map<string, string> settings:
        description: Configuration key-value pairs
      array<string> enabled_features:
        description: List of enabled feature names

Validation Rules

Schema Validation

Name uniqueness - Schema names must be unique
Field uniqueness - Field names must be unique within a schema
Type validity - Field types must be valid
Reference validity - Referenced schemas must exist
No circular references - Schemas cannot reference themselves directly or indirectly

Field Validation

Name format - Field names should be valid identifiers
Type compatibility - Types must be compatible with language targets
Array length - Fixed-length arrays must have positive length
Map key types - Only specific types allowed as map keys

Code Generation

Schemas automatically generate type definitions in multiple languages:

Rust

#[derive(Copy, Clone, Debug)]
#[repr(C)]
pub struct TemperatureReading {
    pub temperature: f32,
    pub timestamp: u64,
}

Python

@dataclass
class TemperatureReading:
    temperature: float
    timestamp: int

C++

struct TemperatureReading {
    float temperature;
    uint64_t timestamp;
};

Best Practices

Descriptive Names

Use clear, descriptive schema and field names. “TemperatureReading” is better than “Data”.

Add Descriptions

Document schemas and fields. Future you will thank you.

Reuse Schemas

Define common schemas once and reuse them. Don’t duplicate definitions.

Organize by Domain

Group related schemas in the same file. Keep schemas organized.

Common Patterns

Timestamp Pattern

Most schemas include a timestamp:

fields:
  uint64 timestamp:
    description: Unix timestamp in milliseconds

ID Pattern

Include identifiers for tracking:

fields:
  string id:
    description: Unique identifier

Metadata Pattern

Use maps for flexible metadata:

fields:
  map<string, string> metadata:
    description: Additional key-value metadata

Troubleshooting

Schema validation errors

Problem: Schema fails validation.Solutions:

Check for syntax errors (YAML formatting)
Verify schema names are unique
Check field types are valid
Ensure referenced schemas exist
Look for circular references

Type generation errors

Problem: Code generation fails for a schema.Solutions:

Check that field types are supported in target languages
Verify array/map syntax is correct
Ensure nested schemas are valid
Check for reserved keywords in field names

Schema not found

Problem: Referenced schema doesn’t exist.Solutions:

Verify schema file exists in schemas/ directory
Check schema name matches exactly (case-sensitive)
Ensure schema file is valid YAML
Reload project to refresh schema cache

Next Steps

Create a Schema

Step-by-step guide to creating schemas.

Schemas Concept

Understand how schemas work in Cerulion.

Naming Conventions

Follow naming conventions for schemas.

Examples

See schemas in action with examples.

Cerulion Graph Editor

Cerulion Core

Cerulion RCL Hooks

Cerulion Visualization

Cerulion CLI

Cerulion Launch

Cerulion Serialization

​Schema YAML Reference

​File Structure

​Basic Structure

​Schema Definition

​Schema Name

​Description

​Field Types

​Primitive Types

​Numeric Types

​Other Primitives

​Collection Types

​Arrays

​Maps

​Schema References

​Field Definition

​Basic Field

​Field with Description

​Field Examples

​Complete Examples

​Simple Schema

​Complex Schema

​Array and Map Examples

​Validation Rules

​Schema Validation

​Field Validation

​Code Generation

​Rust

​Python

​C++

​Best Practices