Entity Manager (definitions, follows, instances and relations)
The Entity Manager is Nimobase's data layer: it lets you declare entities with a field schema, version them and publish them into a platform or company catalogue, which a tenant can follow, accept or fork from a platform entity without installing an application, create / read / update / delete / restore instances against the published version in force, query those instances with declared filters and search, and associate N:N pairs with delete policies. OWNER and ADMIN manage definitions and instances. The OWNER can grant a MEMBER a dashboard grant per entity with explicit capabilities (read / create / update / delete); without a grant (or with the requested capability set to false) the MEMBER receives 403 on that dashboard operation. That grant does not authorize App Data or the application plane. Accepting a later version is rejected (409) when there are active instances that do not satisfy the new schema; soft deletes do not block.
Access boundary: operating on a tenant catalogue or instance requires an active UserCompany membership in that company, and its roles/grants apply. The Super Admin role only authorizes the platform catalogue; it grants no access to a tenant's catalogue or data. X-Company-Id can select only a company the user is a member of.
Instances and relations created from the runtime are isolated by environmentId, derived on the server after authorizing project, environment and release. Reads, writes, references, query joins and uniqueness validation are limited to that environment; reference IDs from another environment are rejected. Earlier records and Entity Manager operations stay on the administrative company plane.
Key concepts
- Two catalogues: platform (
companyIdnull) and tenant (one company). A tenant never sees another tenant's definitions or follows. - DSL cycle: draft → validation → version → publication. Only a published version is in force. A draft is not treated as an executable schema.
- Immutability: a published version is not edited. A change creates a new version; the previous one remains.
- Follow without copying: following a platform entity does not copy it into the tenant catalogue. It leaves a pin to the specific published version.
- The pin does not move when the Super Admin publishes vN+1. OWNER/ADMIN accept that version when it suits them.
- Fork: copies the pinned version into the tenant catalogue (published, in force) and cuts the follow. The platform original does not change. Later platform versions do not apply.
- Platform retirement: a Super Admin can only retire a global version when no tenant follows are still pinned to it. If any remain, the operation returns a generic 409 without enumerating or modifying follows, roles or data. OWNER/ADMIN must perform an authorized manual fork from their company before retrying.
- Minimal application: the Super Admin publishes a platform application that declares entities. Following that app pins those entities (the same pins). Extra entities can be followed separately.
- N:1 references: a
referencefield stores another instance's id. On write the target must exist in this tenant (or be an instance of a platform entity the tenant follows). If missing → 400. A platform entity cannot reference a tenant's catalogue. There are no cross-tenant links. - Field types: string, text, integer, decimal, boolean, datetime, enum (closed list), reference (N:1 to another authorized entity), file (a reference to one object in that tenant's space; never the binary). A string/text field may also carry a semantic format from the closed catalogue
email,urloruuid, validated in addition to the structural type (it does not replace it). - Embedded object and list (Entity IR v2): an
objectfield (withfields[]) or alist(withitems) is stored inline in the instance. An object is not a relation: it accepts noreferenceorfileinside, noronDelete. See "Embedded objects and lists". - Computed fields (Entity IR v3): a top-level field can be derived from top-level fields of the same entity with the Canonical Expression IR. The server computes the value when returning the instance; it is not persisted and the API rejects client writes. See "Computed fields".
- Native N:N relations: declared in the JSON (
name+ two entities +onDelete). It is not a list field. OWNER/ADMIN associate and dissociate published pairs. If it is reflexive (the same entity on both sides) it requires a different role per side (e.g. parent / child). - Delete policy: every N:1 and every N:N declares
onDelete:restrict(blocks when origins exist),setNull(empties the field or removes the link; forbidden when the N:1 is required) orcascade(deletes the origins too; an unresolvable cycle is rejected). The soft delete (DELETEon an instance) applies those policies:restrict→ 409 and nothing is deleted. IfsetNullorcascadetouch several instances, every write runs in a single transaction (all or nothing). - Unique name per catalogue. On a clash the API answers 409 with unused suggestions.
- Limits: 50 fields and 10 relations per entity (N:1 + N:N), 50 instances per page and 200 search characters. Only the Super Admin changes them in Settings (
entity_manager_max_fields_per_entity,entity_manager_max_relations_per_entity,entity_manager_max_instances_per_page,entity_manager_max_search_characters): an actor who is not a Super Admin receives 403 and the current maximum is preserved; a value that is not an integer ≥ 1 is rejected with 400 (the default is not silently restored). - Queries: the schema declares which fields (or combinations) are
filterable/sortableand which string/text/enum fields aresearchable. The listing filters by equality, range, contains, in and empty; sorts by a declared field; searches text across the searchable ones; and can use fields of entities related through N:1 or N:N (customer.name,order_products.sku). A field not declared for that use → 400. An emptyqis ignored (it does not match everything). - Permissions: the Super Admin manages the platform catalogue (including retirement). OWNER and ADMIN manage their company's, follows, acceptance, fork and instances without a grant. MEMBER does not manage definitions. For dashboard instances, the OWNER grants per entity with
read/create/update/delete; the operation only passes when that capability istrue. ADMIN neither grants nor revokes. - Instances: only against a published version in force. If the tenant has the entity in its catalogue, that published version is used; otherwise the pinned schema of a platform follow is used. The route's
:entityNameis case-insensitive. If the entity exists but only has a draft (no published version in force) → 400. If the name resolves to neither a tenant catalogue entity nor a platform follow → 404. A draft accepts no instance writes or listings. - Validation before persisting: type, required, unique (single or composite; empty values do not participate), min/max length or magnitude, string pattern, semantic format (
email/url/uuid), and conditionals ("if A equals X, B becomes required or forbidden"). - Bounded declarative pattern: a
patternis schema data, never tenant code. It is rejected when declaring the field if it exceeds 200 characters or is susceptible to catastrophic backtracking (nested repetition such as(a+)+, ambiguous alternation such as(a|a)+). No engine timeout is trusted. Semantic formats are the preferred evolution over free patterns. - Extra fields: rejected (not trimmed).
referencerequires the target to exist in the tenant. - File field: the value is the object's relative path in the tenant's space. With
object_storage_enabled, writing requires a live file in that space (another tenant, platform, backups or missing → 400). If the object is deleted afterwards,GET/LISTstill return the instance and list the field inbrokenFileFields(not 404). OnPATCH, a required file field or one present in the body requires a live reference; an untouched optional one may stay broken. Without the entitlement, a schema withfilefields can still be published; on read and write those fields are ignored (trimmed, not a 400 for being present) andbrokenFileFieldsis empty. - Identity: a unique UUID in the tenant + entity scope;
createdAtandupdatedAtare recorded. - Soft delete:
DELETEmarks the instance (deletedAt). It disappears from listings and fromGETby id (404). OWNER/ADMIN can restore it by id even though the public get answers 404. Soft deletes do not participate in unique: another instance with the same value can be created. Restoring while that unique is held by an active instance → 409. - Isolation: a tenant neither reads nor writes another tenant's instances. A cross-tenant get answers 404 without leaking data.
Endpoints
All require Authorization: Bearer <token>. space is platform or tenant.
| Method | Route | Who |
|---|---|---|
POST | /entity-manager/:space/definitions | Platform: Super Admin. Tenant: active OWNER/ADMIN member |
GET | /entity-manager/:space/definitions | Same |
GET | /entity-manager/:space/definitions/:id | Same — 404 when it belongs to another catalogue |
PATCH | /entity-manager/:space/definitions/:id | Updates a draft; when the last version is published, creates a new one |
POST | /entity-manager/:space/definitions/:id/publish | Publishes the draft when valid |
POST | /entity-manager/:space/definitions/:id/versions | Creates a draft from the published version |
POST | /entity-manager/tenant/follows | OWNER/ADMIN — follow a platform entity (definitionId or name) |
GET | /entity-manager/tenant/follows | OWNER/ADMIN — the tenant's pins |
POST | /entity-manager/tenant/follows/:followId/accept | OWNER/ADMIN — accept a later version; 409 when active instances do not satisfy it |
POST | /entity-manager/tenant/follows/:followId/fork | OWNER/ADMIN — copy the pinned version and cut the follow |
POST | /entity-manager/platform/definitions/:id/versions/:version/retire | Super Admin — retire a global version only; generic 409 when follows remain; does not mutate tenant relations |
POST | /entity-manager/platform/applications | Super Admin — draft (name, declaredEntities) |
GET | /entity-manager/:space/applications | Platform: Super Admin. Tenant: active OWNER/ADMIN member (forked copies) |
GET | /entity-manager/:space/applications/:id | Same |
PATCH | /entity-manager/platform/applications/:id | Super Admin |
POST | /entity-manager/platform/applications/:id/publish | Super Admin |
POST | /entity-manager/platform/applications/:id/versions | Super Admin |
POST | /entity-manager/platform/applications/:id/versions/:version/retire | Super Admin — retire a global version only; generic 409 when follows remain; does not mutate tenant relations |
POST | /entity-manager/tenant/application-follows | OWNER/ADMIN — follow an app and pin its declared entities |
GET | /entity-manager/tenant/application-follows | OWNER/ADMIN |
POST | /entity-manager/tenant/application-follows/:followId/accept | OWNER/ADMIN — 409 when active instances do not satisfy the schema |
GET | /entity-manager/tenant/permissions | OWNER — lists dashboard grants (per entity and capability) |
PUT | /entity-manager/tenant/permissions/:userId | OWNER — upsert a MEMBER's grant ({ entity, grant }) |
DELETE | /entity-manager/tenant/permissions/:userId/:entityName | OWNER — revokes that entity's grant — 204 |
DELETE | /entity-manager/tenant/permissions/:userId | OWNER — revokes every grant of the MEMBER — 204 |
POST | /entity-manager/tenant/entities/:entityName/instances | OWNER/ADMIN, or a MEMBER with create on that entity — create an instance ({ payload }); :entityName case-insensitive; draft only → 400; unknown → 404 |
GET | /entity-manager/tenant/entities/:entityName/instances | OWNER/ADMIN, or a MEMBER with read — paginated list { data, total, page, limit }; :entityName case-insensitive; draft only → 400; unknown → 404; skips soft deletes |
GET | /entity-manager/tenant/entities/:entityName/instances/:instanceId | OWNER/ADMIN, or a MEMBER with read — :entityName case-insensitive; draft only → 400; unknown → 404; 404 when missing, soft deleted or from another tenant; orphaned file → 200 + brokenFileFields |
PATCH | /entity-manager/tenant/entities/:entityName/instances/:instanceId | OWNER/ADMIN, or a MEMBER with update — merges payload and revalidates |
DELETE | /entity-manager/tenant/entities/:entityName/instances/:instanceId | OWNER/ADMIN, or a MEMBER with delete — soft delete — 204; restrict → 409 |
POST | /entity-manager/tenant/entities/:entityName/instances/:instanceId/restore | OWNER/ADMIN, or a MEMBER with update — restores — 200; unique taken → 409 |
POST | /entity-manager/tenant/entities/:entityName/relations/:relationName/links | OWNER/ADMIN, or a MEMBER with update — associate an N:N pair ({ leftInstanceId, rightInstanceId }) |
DELETE | /entity-manager/tenant/entities/:entityName/relations/:relationName/links | OWNER/ADMIN, or a MEMBER with update — dissociate the pair — 204 |
POST | /entity-manager/tenant/entities/:entityName/instances/:instanceId/apply-relation-policies | OWNER/ADMIN, or a MEMBER with delete — test hook: policies + hard remove — 204; restrict → 409 |
Dashboard grant (MEMBER)
PUT /entity-manager/tenant/permissions/:userId
Content-Type: application/json
{
"entity": "customers",
"grant": { "read": true, "create": true, "update": false, "delete": false }
}200 with the persisted grant. Upsert by (user, entity). Only the OWNER grants or revokes; ADMIN → 403. If the target is not a MEMBER of the company → 400; if they are not a member at all → 404.
With that grant the MEMBER can list/read customers and create instances; a PATCH or DELETE on that entity → 403 (capability false). With no row for another entity → 403 on any operation on that other entity.
DELETE /entity-manager/tenant/permissions/:userId/customers204 — revokes only the customers grant. Without /:entityName, every grant of the MEMBER is revoked.
Following and accepting
POST /entity-manager/tenant/follows
Content-Type: application/json
{ "name": "PlatformCustomer" }201 with pinnedVersion (the published one in force). The tenant catalogue does not include that definition. If the platform publishes v2, pinnedVersion stays the same until:
POST /entity-manager/tenant/follows/:followId/accept
{ "version": 2 }Fork
POST /entity-manager/tenant/follows/:followId/forkCopies the pinned version as its own definition (inForceVersion = 1, forkedFromDefinitionId pointing at the platform) and removes the follow.
Instances
POST /entity-manager/tenant/entities/Customer/instances
Content-Type: application/json
{ "payload": { "title": "Acme" } }201 with id (UUID), payload, brokenFileFields (array of file field names whose reference is missing), createdAt and updatedAt. GET and PATCH use the same id and only see active instances. A field not declared in the schema → 400. A reference whose target does not exist (or is soft deleted) → 400. A file outside the tenant's space (or pointing at platform/backups) → 400. A MEMBER without a grant (or without the requested capability) → 403.
GET /entity-manager/tenant/entities/Customer/instances?page=1&limit=50&sort=title&order=asc&q=acme&filters=[{"field":"kind","op":"eq","value":"company"}]200 { data, total, page, limit }. Omitting page means the first one. A limit above the current maximum → 400. filters operators: eq, gt, gte, lt, lte, contains, in, empty, notEmpty.
DELETE /entity-manager/tenant/entities/Customer/instances/:id204. The instance disappears from GET .../instances and GET .../instances/:id answers 404. Restoring:
POST /entity-manager/tenant/entities/Customer/instances/:id/restore200 and it returns to the listing. If another active instance already holds a unique value → 409.
Semantic formats and patterns
A string or text field can declare a format from the closed catalogue (email, url, uuid) and/or a pattern, on top of the structural type. Both are validated when writing instances:
POST /entity-manager/tenant/definitions
Content-Type: application/json
{
"name": "Customer",
"schema": {
"fields": [
{ "name": "email", "type": "string", "format": "email" },
{ "name": "site", "type": "string", "format": "url" },
{ "name": "ref", "type": "string", "format": "uuid" },
{ "name": "code", "type": "string", "pattern": "^[A-Z]{3}-[0-9]+$" }
]
}
}- A
formatoutside the catalogue, or on a field that is notstring/text→ 400. - An invalid
pattern, longer than 200 characters or susceptible to catastrophic backtracking ((a+)+,(a|a)+…) → 400 when declaring the field or publishing. No engine timeout is trusted;formats are the preferred evolution over free patterns. - When writing an instance, a value that does not satisfy the declared
formatorpattern→ 400.
Embedded objects and lists
An object field declares its own fields[]; a list field (list<T>) declares items (string, text, integer, decimal, boolean, datetime, enum or object) and optionally minItems/maxItems:
POST /entity-manager/tenant/definitions
Content-Type: application/json
{
"name": "Order",
"schema": {
"fields": [
{ "name": "title", "type": "string", "required": true },
{ "name": "address", "type": "object", "fields": [
{ "name": "street", "type": "string", "required": true },
{ "name": "zip", "type": "string", "pattern": "^[0-9]{5}$" }
]},
{ "name": "tags", "type": "list", "items": { "type": "string", "maxLength": 20 }, "maxItems": 5 },
{ "name": "lines", "type": "list", "items": { "type": "object", "fields": [
{ "name": "sku", "type": "string", "required": true },
{ "name": "qty", "type": "integer", "min": 1 }
]}}
]
}
}- The schema is stamped with
irVersion: 2only when it usesobject/list; earlier schemas do not change.irVersion: 1with object/list → 400. reference/fileinside an object or list,list<list<T>>,arrayandproperties→ 400. At most 3 nesting levels, 100 elements per list, and every field in the tree counts against the field limit.- These fields (and the embedded ones) accept no
unique,filterable,sortableorsearchable, norfield.subfieldpaths; they can be the target of a conditional. - In an instance, a value of the wrong type, a missing required embedded field, an undeclared key inside the object, an invalid or null element, or a list outside
minItems/maxItems→ 400, with the path (address.street,tags[2]). PATCHreplaces the whole value of theobject/listfield it is sent.
Computed fields
A top-level field can declare computed with a Canonical Expression IR node. The expression may read top-level fields of the same entity and use other computed fields; nonexistent fields, nested paths, invalid operators or arities, and cycles are rejected when validating the definition.
{
"fields": [
{ "name": "unitPrice", "type": "decimal", "required": true },
{ "name": "quantity", "type": "integer", "required": true },
{
"name": "total",
"type": "decimal",
"computed": {
"op": "mul",
"args": [{ "field": "unitPrice" }, { "field": "quantity" }]
}
}
]
}- The schema is stamped with
irVersion: 3when it includes computed fields. Existing v1/v2 schemas keep their version and representation. - The server evaluates and validates the result against the declared type and constraints on create and update, and recomputes it in the create, update, get and list responses. The derived value is not stored in
payload; any attempt to send it in a write → 400. - Only top-level dependencies of the same entity are allowed. Dependencies on
filefields are rejected so entitlement filtering cannot be bypassed; nested or cross-entity dependencies are rejected too. A top-levelreferencemay be used as local data (its id) without resolving the other entity's data. Computed fields cannot have typereferenceorfile, because those types require asynchronous target/object validation, nor participate inunique, query declarations or conditional rules. They run on the server only.
N:N relations
POST /entity-manager/tenant/entities/Order/relations/order_products/links
Content-Type: application/json
{ "leftInstanceId": "<order-uuid>", "rightInstanceId": "<product-uuid>" }201 with the link. DELETE to the same path with the same body → 204. A missing endpoint or one from another tenant → 400 without leaking foreign data.
Related
- Settings — maximum fields, relations, page size and search
- Roles and permissions
- Object storage — the object space the file field type references