Skip to content

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 (companyId null) 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 reference field 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, url or uuid, validated in addition to the structural type (it does not replace it).
  • Embedded object and list (Entity IR v2): an object field (with fields[]) or a list (with items) is stored inline in the instance. An object is not a relation: it accepts no reference or file inside, nor onDelete. 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) or cascade (deletes the origins too; an unresolvable cycle is rejected). The soft delete (DELETE on an instance) applies those policies: restrict → 409 and nothing is deleted. If setNull or cascade touch 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 / sortable and which string/text/enum fields are searchable. 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 empty q is 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 is true. 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 :entityName is 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 pattern is 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). reference requires 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/LIST still return the instance and list the field in brokenFileFields (not 404). On PATCH, 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 with file fields can still be published; on read and write those fields are ignored (trimmed, not a 400 for being present) and brokenFileFields is empty.
  • Identity: a unique UUID in the tenant + entity scope; createdAt and updatedAt are recorded.
  • Soft delete: DELETE marks the instance (deletedAt). It disappears from listings and from GET by 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.

MethodRouteWho
POST/entity-manager/:space/definitionsPlatform: Super Admin. Tenant: active OWNER/ADMIN member
GET/entity-manager/:space/definitionsSame
GET/entity-manager/:space/definitions/:idSame — 404 when it belongs to another catalogue
PATCH/entity-manager/:space/definitions/:idUpdates a draft; when the last version is published, creates a new one
POST/entity-manager/:space/definitions/:id/publishPublishes the draft when valid
POST/entity-manager/:space/definitions/:id/versionsCreates a draft from the published version
POST/entity-manager/tenant/followsOWNER/ADMIN — follow a platform entity (definitionId or name)
GET/entity-manager/tenant/followsOWNER/ADMIN — the tenant's pins
POST/entity-manager/tenant/follows/:followId/acceptOWNER/ADMIN — accept a later version; 409 when active instances do not satisfy it
POST/entity-manager/tenant/follows/:followId/forkOWNER/ADMIN — copy the pinned version and cut the follow
POST/entity-manager/platform/definitions/:id/versions/:version/retireSuper Admin — retire a global version only; generic 409 when follows remain; does not mutate tenant relations
POST/entity-manager/platform/applicationsSuper Admin — draft (name, declaredEntities)
GET/entity-manager/:space/applicationsPlatform: Super Admin. Tenant: active OWNER/ADMIN member (forked copies)
GET/entity-manager/:space/applications/:idSame
PATCH/entity-manager/platform/applications/:idSuper Admin
POST/entity-manager/platform/applications/:id/publishSuper Admin
POST/entity-manager/platform/applications/:id/versionsSuper Admin
POST/entity-manager/platform/applications/:id/versions/:version/retireSuper Admin — retire a global version only; generic 409 when follows remain; does not mutate tenant relations
POST/entity-manager/tenant/application-followsOWNER/ADMIN — follow an app and pin its declared entities
GET/entity-manager/tenant/application-followsOWNER/ADMIN
POST/entity-manager/tenant/application-follows/:followId/acceptOWNER/ADMIN — 409 when active instances do not satisfy the schema
GET/entity-manager/tenant/permissionsOWNER — lists dashboard grants (per entity and capability)
PUT/entity-manager/tenant/permissions/:userIdOWNER — upsert a MEMBER's grant ({ entity, grant })
DELETE/entity-manager/tenant/permissions/:userId/:entityNameOWNER — revokes that entity's grant — 204
DELETE/entity-manager/tenant/permissions/:userIdOWNER — revokes every grant of the MEMBER — 204
POST/entity-manager/tenant/entities/:entityName/instancesOWNER/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/instancesOWNER/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/:instanceIdOWNER/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/:instanceIdOWNER/ADMIN, or a MEMBER with update — merges payload and revalidates
DELETE/entity-manager/tenant/entities/:entityName/instances/:instanceIdOWNER/ADMIN, or a MEMBER with delete — soft delete — 204; restrict → 409
POST/entity-manager/tenant/entities/:entityName/instances/:instanceId/restoreOWNER/ADMIN, or a MEMBER with update — restores — 200; unique taken → 409
POST/entity-manager/tenant/entities/:entityName/relations/:relationName/linksOWNER/ADMIN, or a MEMBER with update — associate an N:N pair ({ leftInstanceId, rightInstanceId })
DELETE/entity-manager/tenant/entities/:entityName/relations/:relationName/linksOWNER/ADMIN, or a MEMBER with update — dissociate the pair — 204
POST/entity-manager/tenant/entities/:entityName/instances/:instanceId/apply-relation-policiesOWNER/ADMIN, or a MEMBER with delete — test hook: policies + hard remove — 204; restrict → 409

Dashboard grant (MEMBER) ​

http
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.

http
DELETE /entity-manager/tenant/permissions/:userId/customers

204 — revokes only the customers grant. Without /:entityName, every grant of the MEMBER is revoked.

Following and accepting ​

http
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:

http
POST /entity-manager/tenant/follows/:followId/accept
{ "version": 2 }

Fork ​

http
POST /entity-manager/tenant/follows/:followId/fork

Copies the pinned version as its own definition (inForceVersion = 1, forkedFromDefinitionId pointing at the platform) and removes the follow.

Instances ​

http
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.

http
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.

http
DELETE /entity-manager/tenant/entities/Customer/instances/:id

204. The instance disappears from GET .../instances and GET .../instances/:id answers 404. Restoring:

http
POST /entity-manager/tenant/entities/Customer/instances/:id/restore

200 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:

http
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 format outside the catalogue, or on a field that is not string/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 format or pattern → 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:

http
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: 2 only when it uses object/list; earlier schemas do not change. irVersion: 1 with object/list → 400.
  • reference/file inside an object or list, list<list<T>>, array and properties → 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, sortable or searchable, nor field.subfield paths; 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]).
  • PATCH replaces the whole value of the object/list field 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.

json
{
  "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: 3 when 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 file fields are rejected so entitlement filtering cannot be bypassed; nested or cross-entity dependencies are rejected too. A top-level reference may be used as local data (its id) without resolving the other entity's data. Computed fields cannot have type reference or file, because those types require asynchronous target/object validation, nor participate in unique, query declarations or conditional rules. They run on the server only.

N:N relations ​

http
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.