Collections

Collections are the foundation of a Norbital workspace. Each collection represents a business entity, but it also carries the metadata that makes that entity usable across interfaces, pages, permissions, exports, and automations.

Definition

A collection in the blueprint combines:

• table_metadata for columns and structure
• include_map for relationship expansion
• record_label for human-readable display labels
• form_codeblock for the record interface, when customized
• Per-route metadata for list, view, create, update, and delete

1. Design The Collection Around A Workflow

Before creating columns, decide what the collection is for. A good collection design answers three questions clearly:

• What is the business object?
• What fields are required to operate it day to day?
• Which relationships need to be traversed elsewhere in the workspace?

2. Column Planning

Norbital supports the usual business-app field patterns, including text, numbers, booleans, dates, and record links.

As a configurator, the important rule is to keep the first version of the schema focused:

• Add fields users will actually read or edit.
• Prefer links to separate collections when the data has its own lifecycle.
• Avoid speculative columns that exist only because they might be useful later.

3. include_map

The include_map controls which relationships are expanded when the collection is queried. It is about related records, not scalar columns.

Use it to make linked data available where it is actually needed, such as:

• A project table that needs owner details
• An approval view that needs a supplier and its finance contact
• A notification template that needs fields from a linked customer record

4. Record Labels

The record_label is a CEL expression that computes the display label for a record. This label appears throughout the product anywhere a record needs to be identified by people.

A useful record label usually combines the most recognizable field with a status or qualifier.

"Project: " + data.name + " (" + data.status + ")"

Good record labels help with:

• Linked-record selectors
• Notifications and approvals
• Task context and dashboard readability

5. Route Metadata

Every collection ships with five standard routes. You then attach route-specific behavior to them:

• list and view can define export behavior.
• create, update, and delete can define validation and notifications.
• create and update can also define import behavior.

6. What Happens When You Save

Saving collection changes in Database Studio updates the staged blueprint in your active fork and runs configuration checks. It does not immediately apply DDL to production.

Recommended Setup Sequence

1. Create the collection and its essential columns.
2. Set the record label.
3. Define only the relationship expansion you need.
4. Generate or customize the record interface.
5. Add route behavior, permissions, and approvals.