Schema Editor

The Schema Editor is an administrative application for viewing and editing ControlBird's entity type definitions. Every entity is an instance of an entity type, and each type declares a set of named fields with specific data types and storage scopes. With the Schema Editor you can create new entity types, manage field inheritance through type hierarchies, add and remove direct fields, and save those changes so they persist.

Access & Requirements

Opening the Schema Editor requires schema-editing permission, so it is intended for administrators and developers shaping the data model rather than day-to-day operators.

Core Concepts

A schema describes an entity type and the fields it owns. ControlBird distinguishes between the fields a type declares directly and the full set of fields it has after inheritance, and it exposes both views in the editor.

The Workspace

The editor is a two-panel layout. The left panel is a searchable, paginated tree of entity types; the right panel shows the schema of whichever type you select.

• Type tree (left): root entity types and their descendants, built from inheritance relationships. Roots are paginated 25, 50, or 100 per page.
• Entity header (right): the selected type's name, type ID, parent names, direct field count, and total field count.
• Direct Fields: a sortable, editable table of fields declared on the selected type.
• Inherited Fields: a read-only table of fields contributed by parent types.
• Add Field: a form for declaring a new field on the current type.

Keyboard shortcuts

Field Data Types

Each field has a kind (its data type) which determines the value it can hold and its default. The available kinds are:

Choice fields

A Choice field carries a choices array of options plus a default index. You enter the options as a comma-separated list and pick which one is selected by default. A choice field must have at least one option, and the default index must fall within [0, choices.length - 1].

Storage Scope

Every field has a storage scope that controls whether it is persisted. This is the most important property to get right, because it decides whether a field survives a restart.

Structural fields (Name, Parent, and Children) are handled separately from the schema and are not treated as Configuration-scoped fields.

Field Rank

Rank is a numeric sort order that controls how fields are displayed. Fields are sorted by rank, then alphabetically by name as a tie-breaker. Fields without an explicit rank fall back to the order in which they were defined.

How Schemas Are Persisted

When you save a schema, the definitions of every entity type and its Configuration-scoped fields are persisted so they survive a restart. Runtime-scoped fields and structural fields are not persisted. The editor keeps the on-screen tree and field counts in sync after each save.

Editing a Schema: Step by Step

1. Open the Schema Editor from the platform UI. It lists all entity types, then loads each type's fields when you select it.
2. Browse or search the type tree on the left and click an entity type to select it.
3. Review the Direct Fields table (name, kind, rank, storage scope, default or options, and a remove action) and the read-only Inherited Fields table.
4. In the Add Field section, enter a field name, select a kind, set the rank and storage scope, and supply kind-specific configuration (a default value, or options for a Choice field).
5. Click Add Field. The new field appears in the Direct Fields table.
6. Edit field properties inline. Changing rank or storage scope marks the schema as having unsaved changes, and the editor warns you before you navigate away.
7. Remove direct fields you no longer need. Inherited fields cannot be modified here; edit the parent type instead.
8. Click Save Changes to persist the updated fields, or Reset to discard unsaved edits and reload the saved schema.

Creating a New Entity Type

1. Click New Entity Type (or press Ctrl+N) to open the create form.
2. Enter the type name and optionally select one or more parent types to inherit fields from.
3. Click Create. The new type is assigned an identifier and saved with the parent types you selected.
4. The new type appears in the tree, nested under its parent. Select it to begin adding direct fields.

Example: a Choice field on an existing type

Suppose you want to add a status indicator to a type. In the Add Field section, set the name to Status, the kind to Choice, the options to Idle,Processing,Error, and the default index to 0. After saving, the Direct Fields table shows Status with three options and Idle selected by default.

Inheritance in Practice

Selecting a type that inherits from a parent illustrates how the two views work together. The Inherited Fields table shows the fields contributed by the parent type, while the Direct Fields table shows the fields declared on the selected type itself. A type can inherit from more than one parent.

A child type combines its own direct fields with the direct and inherited fields of every parent it inherits from. Circular inheritance is not permitted and is rejected when you save.

Limitations

• Entity type identifiers are assigned on creation and cannot be renamed afterward.
• Inherited fields are read-only here; modify them on the parent type.
• Field names must be unique within a type.
• Choice fields require at least one option, and the default index must be in range.
• Circular inheritance is rejected on save, with an error surfaced in the editor.
• Field removal persists immediately, without a confirmation dialog.
• Very large schemas (more than ~100 types) may impact tree-rendering performance.

Next Steps

With your types defined, populate and lay out instances in the Model Builder, inspect the resulting data in the Database Browser, or review how field changes propagate through the Data Model and Notifications & Reactivity.