Skip to main content

​
Schemas

Schemas define the structure and type of data passed between nodes. Think of them as blueprints that describe what data looks like—similar to a struct in C/Rust, a class in Python, or a type in TypeScript. Schemas are how the editor enforces type-safe wiring: nodes can only connect when data types are compatible.

​
What is a Schema?

A schema is a definition that describes:
  • Field names - What data is called (e.g., temperature, timestamp)
  • Field types - What kind of data it is (e.g., float32, uint64, string)
  • Field descriptions - What the data means (optional but recommended)
Think of schemas as contracts. When you define a schema, you’re saying “any data using this schema will have these fields with these types.” Nodes can only connect if their schemas are compatible.
Schemas are similar to database schemas, API request/response types, or message formats in other systems. They provide structure and type safety.

​
Why Use Schemas?

Type Safety

Prevent runtime errors by catching type mismatches at design time. The editor won’t let you connect incompatible types.

Documentation

Schemas document what data looks like. Field descriptions explain what each field means.

Code Generation

Schemas automatically generate type definitions in Rust, Python, and C++. Write once, use everywhere.

Validation

The framework validates data against schemas, catching errors before they cause problems.

​
Schema File Format

Schemas are stored as .yaml files in the schemas/ directory of your project. A schema file can contain one or more schema definitions.

​
Basic Schema Structure

schemas:
  SchemaName:
    description: Optional description of what this schema represents
    fields:
      field_name: field_type
        description: Optional description of this field

​
Example Schema

schemas:
  TemperatureReading:
    description: Temperature and pressure readings from a sensor
    fields:
      float temperature:
        description: Temperature in Celsius
      float pressure:
        description: Pressure in hPa
      uint64 timestamp:
        description: Unix timestamp in nanoseconds

​
Supported Field Types

Schemas support these primitive types:

​
Numeric Types

  • int8, int16, int32, int64 - Signed integers
  • uint8, uint16, uint32, uint64 - Unsigned integers
  • float32, float64 - Floating point numbers
  • bool - Boolean values

​
Text Types

  • string - Variable-length text
  • bytes - Raw binary data

​
Collection Types

  • array<type> - Fixed or variable-length arrays
  • map<key_type, value_type> - Key-value mappings
For complex nested structures, you can reference other schemas as field types. This allows you to build complex data structures from simpler ones.

​
Schema Examples

​
Simple Sensor Data

schemas:
  SensorData:
    description: Basic sensor reading
    fields:
      float32 value:
        description: Sensor reading value
      uint64 timestamp:
        description: When the reading was taken

​
Complex Nested Structure

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

  Pose:
    description: Position and orientation
    fields:
      Point3D position:
        description: 3D position
      array<float32> orientation:
        description: Quaternion [x, y, z, w]
        length: 4

​
Array and Map Types

schemas:
  SensorArray:
    description: Multiple sensor readings
    fields:
      array<float32> readings:
        description: Array of sensor values
        length: 10  # Fixed length array

  Metadata:
    description: Key-value metadata
    fields:
      map<string, string> tags:
        description: String key-value pairs

​
Where Schemas Live

Schemas are stored in your project’s schemas/ directory: 
my-project/
  schemas/
    sensors.yaml
    geometry.yaml
    common.yaml
  nodes/
  graphs/
You can organize schemas across multiple files. The editor loads all .yaml files in the schemas/ directory.

​
Schema Validation

The editor validates schemas when you:
  1. Save a schema file - Checks for syntax errors
  2. Connect nodes - Ensures port types match
  3. Generate code - Validates all schemas are correct

​
Common Validation Errors

  • Missing fields - Referenced schema doesn’t exist
  • Type mismatch - Field type is invalid
  • Circular references - Schemas reference each other in a loop
  • Syntax errors - Invalid YAML syntax
Fix validation errors before generating code. Code generation will fail if schemas are invalid.

​
Schema Best Practices

Descriptive Names

Use clear, descriptive schema names. “TemperatureReading” is better than “Data” or “Schema1”.

Add Descriptions

Document what schemas and fields mean. Future you (and your team) 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 by purpose.

​
Schema Evolution

Over time, you may need to change schemas. Here are some guidelines:

​
Safe Changes (Backward Compatible)

  • Adding optional fields - New fields with default values
  • Renaming fields - If you update all nodes simultaneously
  • Adding to arrays - Extending array length

​
Breaking Changes (Require Updates)

  • Removing fields - Nodes expecting these fields will break
  • Changing field types - Type mismatches will occur
  • Renaming schemas - All references must be updated
Breaking changes require updating all nodes that use the schema. Plan schema changes carefully, especially in production systems.

​
Code Generation from Schemas

Schemas automatically generate type definitions in multiple languages:

​
Rust

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

​
Python

@dataclass
class TemperatureReading:
    temperature: float
    pressure: float
    timestamp: int

​
C++

struct TemperatureReading {
    float temperature;
    float pressure;
    uint64_t timestamp;
};
The framework generates these types automatically when you build your project. You don’t need to write them manually.

​
Next Steps

Now that you understand schemas, learn how to use them:

Create a Schema

Step-by-step guide to creating your first schema.

Schema YAML Reference

Complete reference for schema YAML syntax.

Topics

Learn how topics use schemas to ensure type safety.

Nodes

Understand how nodes use schemas for input and output types.