Skip to main content

​
Create a Schema

This guide walks you through creating your first schema. Schemas define the structure of data that flows between nodes, ensuring type safety and preventing runtime errors.

​
Prerequisites

Before you begin, make sure you have:

Project Created

A Cerulion project created and open in the Graph Editor.

Basic YAML Knowledge

Familiarity with YAML syntax (optional, but helpful). We’ll show examples.

Data Structure in Mind

An idea of what data structure you need (fields and types).

Graph Editor Open

Cerulion Graph Editor running and ready to use.
If you don’t have a project yet, see the Quickstart Guide to create one first.

​
What You’ll Create

You’ll create a schema file that defines a data structure. For this example, we’ll create a TemperatureReading schema with temperature, pressure, and timestamp fields.

​
Step-by-Step Guide

1

Open schema editor

In the Graph Editor, click Schema in the toolbar (or press S key).
The schema editor dialog should open, showing an empty schema form.
You can also right-click in the schemas panel (left sidebar) and select “New Schema” from the context menu.
2

Enter schema name

In the schema name field, enter a descriptive name:
  • Use PascalCase (e.g., TemperatureReading, SensorData)
  • Be descriptive and specific
  • Avoid generic names like Data or Message
For this example, enter: TemperatureReading
The schema name should appear in the editor header.
Schema names must be unique within your project. If you see a “name already exists” error, choose a different name.
3

Add description (optional)

In the description field, add a brief explanation of what this schema represents:
Temperature and pressure readings from a sensor, with timestamp
Descriptions are optional but highly recommended. They help you and others understand what the schema is for, especially when revisiting projects later.
4

Add fields

Click Add Field to add your first field. For each field:
  1. Field name: Enter the field name (e.g., temperature)
    • Use camelCase or snake_case (e.g., temperature, sensor_value)
    • Be descriptive
  2. Field type: Select the type from the dropdown:
    • float32 - 32-bit floating point number
    • float64 - 64-bit floating point number
    • int8, int16, int32, int64 - Signed integers
    • uint8, uint16, uint32, uint64 - Unsigned integers
    • bool - Boolean value
    • string - Text string
    • bytes - Binary data
    • Or reference another schema
  3. Field description (optional): Add a description of what this field represents
For this example, add these fields:
  • temperature: float32 - “Temperature in Celsius”
  • pressure: float32 - “Pressure in hPa”
  • timestamp: uint64 - “Unix timestamp in nanoseconds”
You should see all three fields listed in the schema editor.
5

Review schema structure

Review your schema to ensure it’s correct:
  • Name is descriptive and unique
  • Fields have appropriate types
  • Descriptions are clear (if added)
Your schema should look like this:
TemperatureReading:
  description: Temperature and pressure readings from a sensor, with timestamp
  fields:
    temperature: float32
      description: Temperature in Celsius
    pressure: float32
      description: Pressure in hPa
    timestamp: uint64
      description: Unix timestamp in nanoseconds
6

Save the schema

Click Save (or press Ctrl+S / Cmd+S) to save the schema.
The schema should appear in the schemas panel (left sidebar) with a checkmark indicating it’s valid.
The schema is automatically saved to a .yaml file in your project’s schemas/ directory. You can edit it later by double-clicking it in the schemas panel.

​
Understanding the Result

After saving, your schema is:
  • Available to all graphs in your project
  • Ready to use as a port type on nodes
  • Validated for syntax and type correctness
  • Saved in schemas/temperature_reading.yaml (or similar)

​
Using Your Schema

Now you can use this schema when:
  • Creating nodes - Set input/output port types to TemperatureReading
  • Connecting nodes - Ports with matching schema types can connect
  • Code generation - The framework generates type definitions automatically
Try creating a node and setting one of its ports to use TemperatureReading. The editor will show it in the type dropdown.

​
Advanced: Editing Schemas

To edit an existing schema:
  1. Double-click the schema in the schemas panel
  2. Make changes (add/remove fields, change types, etc.)
  3. Save the schema
Changing a schema that’s already in use may break existing nodes. Update all nodes that use the schema, or create a new schema version instead.

​
Troubleshooting

Problem: Error saying schema name is already taken.Solution: Choose a different name. Schema names must be unique within your project.
Problem: Can’t select a field type or type is invalid.Solution:
  • Check that the type is spelled correctly
  • Ensure you’re using a supported type (see field types list above)
  • If referencing another schema, make sure that schema exists
Problem: Created schema but can’t use it when creating nodes.Solution:
  • Verify the schema was saved (check schemas panel)
  • Check for validation errors (red X icon)
  • Try refreshing the project (close and reopen)
  • Ensure you’re in the same project where the schema was created

​
Next Steps

Now that you’ve created a schema, you can:

Connect Nodes

Learn how topics use schemas to enable type-safe connections.

Add Ports

Add ports to nodes and set their types to your schema.

Schema Reference

See the complete schema YAML reference for advanced features.

Schemas Concept

Learn more about how schemas work and best practices.