Data modeling
Describe the business objects. The database and APIs follow.
Take a subscription-billing system: customers, plans, seats, MRR, renewal dates, status. Those objects, their fields, and the relations between them are the core of your business ontology, and on the open-source ObjectStack runtime that core is one compact definition — tables, migrations, the query engine, and REST endpoints are supplied by the runtime. Your agent can write it, your team can fine-tune it field by field in the object designer, and on ObjectOS the in-app AI Builder drafts the same objects and fields from a plain-language request.
- 20+
- Field types — text, currency, percent, lookup, formula, file
- Zero
- Hand-written endpoints — REST APIs come from metadata
- Read-only first
- A database you already run federates in place — read-only by default, writes opt-in, and early
The ontology is the source
One object definition. Schema, rules, and API included.
This is that subscription object: fields, relationships, validation, and history tracking in one reviewable definition. The runtime turns it into tables and migrations, enforces the rules on every write, and serves the API — the same definition an agent can extend and the designer can open.
import { ObjectSchema, Field } from '@objectstack/spec/data';
export const Subscription = ObjectSchema.create({
name: 'billing_subscription',
label: 'Subscription',
searchableFields: ['plan', 'status'],
fields: {
customer: Field.lookup('crm_account', { label: 'Customer', required: true }),
plan: Field.select({
label: 'Plan',
options: [
{ label: 'Starter', value: 'starter', default: true },
{ label: 'Team', value: 'team' },
{ label: 'Business', value: 'business' },
],
}),
seats: Field.number({ label: 'Seats', min: 1 }),
mrr: Field.currency({ label: 'MRR', scale: 2, min: 0 }),
renews_at: Field.date({ label: 'Renews at' }),
status: Field.select({
label: 'Status',
trackHistory: true,
options: [
{ label: 'Active', value: 'active', default: true, color: '#10B981' },
{ label: 'Past due', value: 'past_due', color: '#F59E0B' },
{ label: 'Churned', value: 'churned', color: '#EF4444' },
],
}),
},
});Model the business
Build the subscription system step by step
The ontology stays close to how the business talks: customers, plans, renewals. No ORM classes, no scattered schema files — every step below stays inside one definition.
Objects & relationships
The subscription looks up its customer, invoices hang off it master-detail, tags attach many-to-many — and the runtime keeps referential integrity, so deleting the wrong parent stops being an incident.
Validations & rules
“Seats can’t drop below assigned users.” “MRR can’t go negative.” Constraints are expressions next to the fields they protect, enforced on every write path: UI, API, imports, and AI tools.
Formulas & defaults
“ARR = MRR × 12.” “Renewal defaults to order date + 365.” Computed fields and dynamic defaults use one expression language, so every entry point computes the same answer.
Typed business fields
Currency carries precision and symbol, percent carries its bounds, picklists carry colors and history tracking — field types carry meaning the UI, API, and agents all understand.
The object designer
Fine-tune fields, see the model as a diagram, mount the old database
The definition your agent writes opens as a visual surface in the open-source ObjectStack console — changing a field never requires reading a line of code.
The field editor
Click “+ Add field” to pick from 20+ types, drag rows to reorder, group fields into sections; the right-side inspector edits labels, required flags, options, and colors — every change lands as a draft.
See the diff before publishing
The designer’s review mode compares the draft against the published version item by item — added and modified fields at a glance, the same experience as reviewing an agent’s diff.
The ER diagram
Entity boxes, relationship lines with cardinality labels, auto-layout, and a minimap — the whole data model in one picture, and dragging a line is creating a relationship.
Datasource sync
Connection forms generate from the driver’s schema, “Test connection” verifies it, then pick from the remote table list — introspect an existing ERP or CRM database and mount its tables as governed objects, read-only by default; writes are enabled deliberately, per object.
From model to running system
The parts you never write again
Everything below is generated and kept in sync with the definition — which is exactly why an AI-written change stays a small, reviewable diff.
Tables & migrations
Add a “discount” field to the subscription and the migration appears on Postgres, MySQL, SQLite, Turso, or MongoDB — no SQL scripts to write or sequence.
Query engine
“Subscriptions renewing this month with MRR over 10k” — one query language covers filtering, relations, and aggregation, with the permission model enforced on every request.
REST APIs
CRUD, batch, and discovery endpoints exist the moment an object does — the mobile team starts the next morning, with versioning, docs, and permission checks included.
File storage
Contract PDFs and invoice attachments ride on local disk or S3-compatible storage, with access control following the record they belong to.
Decision surface
What changes, who reviews it, what runs
| Business need | AI writes | Runtime supplies |
|---|---|---|
| Track subscriptions and customers | Objects, fields, relationships | Tables, migrations, referential integrity |
| Seats can never be oversold | One validation expression | Enforcement on UI, API, imports, and AI writes |
| An API for the mobile team | Nothing extra — the object is enough | REST endpoints with permissions and discovery |
| Use the ERP database we already have | A datasource binding, read-only to start | Introspected external tables as governed objects — reads first, writes opt-in per object |
Review checklist
A data review should confirm
- Every object maps to a business concept someone owns.
- Validations live in the definition, not in screens.
- Derived values are formulas, not copy-pasted logic.
- External systems are federated or integrated, not forked.
- API access rides the same permission model as the UI.
FAQ
Frequently asked questions
Which databases can it run on?
Postgres, MySQL, SQLite, Turso, and MongoDB are supported today, and the data layer is driver-based. Federation can additionally mount tables from an external database without moving the data — read-only by default, and early: expect the read path to be the mature one.
What is open source here, and what does ObjectOS add?
All of the data layer: objects, relationships, validations, formulas, migrations, the query engine, REST APIs, file storage, and the object designer, ER diagram, and datasource sync in the Console — Apache-2.0, with no feature gate between development and production. ObjectOS adds the in-app AI Builder, whose built-in tools create packages and objects and add, modify, and delete fields from a chat, queued for human approval before they go live — on Cloud and on Enterprise.
Next pages