Key Concepts

Metadata-driven design

Table and field definitions are stored as data, not as compiled code. When you create a table via the API, oikapi creates it and makes it immediately available – no restarts, no migrations, no compilation.

This means you can modify your schema at runtime. Add a field, change a type, rename a table – all through the API while the system is live.

Note

This is the core idea behind oikapi. Everything – tables, fields, permissions, business rules – is data you manage through the API, not code you deploy.

Applications

Every table belongs to an application – a logical business domain like “CRM” or “HR”. Applications provide:

• Organization – Group related tables together
• Permissions – Grant access to an entire application with one rule
• Boundary enforcement – Business rules can only access tables within their own application (plus system tables)
• Packaging – Export an entire application as a .oikapp file

The system application is special – it contains users, permissions, audit logs, and other platform tables. It’s always accessible from every other application.

Tables and fields

Tables are defined by metadata and can be one of three modes:

Mode	Description
read_write	Full CRUD operations (default)
append_only	Insert-only, no updates or deletes
read_only	Read-only, no modifications

Fields support 30+ types including computed fields (formula, lookup, rollup) and counter fields with auto-incrementing prefixed numbers like INV-00042.

Union views

A union view reads several sibling tables in one application as a single filterable, sortable, keyset-paginable list, with a synthesized column naming the member each row came from.

It is read-only, and it grants nothing: you see rows only from the members you can already read, so adding a union view never widens access to data. Writes go to the member table directly.

Tip

Union views suit unified work lists like “all work” across tasks, incidents, and changes — tables you have deliberately kept separate but often want to read together.

Business rules

Rules are the automation layer. They fire at specific lifecycle points (before create, after update, on field change, on schedule) and can:

• Validate data before it’s saved
• Calculate field values automatically
• Execute JavaScript for complex logic
• Trigger workflows and approval processes
• Call external APIs via the HTTP client
• Use the app cache for rate limiting, memoization, and more

Caution

Rules respect application boundaries – a CRM rule cannot read HR data unless explicitly granted cross-app access. See Applications for details.

Permissions

oikapi uses role-based access control with three levels of granularity:

1. Application-level – Grant a role access to all tables in an application
2. Table-level – Override application permissions for specific tables
3. Field-level – Control read/write access to individual fields

Row-level security (RLS) adds filter expressions to permissions so users only see records matching specific criteria (e.g., “only records where assigned_to equals the current user”).

Grants can target a role, a team, or a dynamic group (a computed collection whose membership is materialized by graph traversal). Per-record sharing additively grants access to an individual record without changing role permissions.

Priority: table-level > per-record grant > application-level > implicit deny. There is no explicit deny – restrict access by not granting it, or override with a more restrictive table grant.

Soft deletion

Nothing is ever permanently deleted:

• Records are marked as deleted and excluded from queries
• Tables and fields are deactivated and hidden from the API

This preserves audit trails and enables recovery. Administrators can restore any deleted item.

Packages

Applications can be exported as .oikapp packages – portable archives that recreate an entire application (tables, fields, permissions, business rules) on any oikapi instance.

Packages support cryptographic signing with trust levels: official, verified, community, and unsigned.

Note

Learn more about building and distributing apps in the Building Apps and Package Format guides.