Entity Manager (definiciones, follow, instancias y relaciones)
El Entity Manager es la capa de datos de Nimobase: permite declarar entidades con un schema de campos, versionarlas y publicarlas en un catálogo de plataforma o de empresa, que un tenant siga, acepte o haga fork de una entidad de plataforma sin instalar una aplicación, crear / leer / actualizar / dar de baja / restaurar instancias contra la versión publicada en vigor, consultar esas instancias con filtros y búsqueda declarados, y asociar pares N:N con políticas de borrado. OWNER y ADMIN gestionan definiciones e instancias. El OWNER puede conceder a un MEMBER un grant de panel por entidad con capacidades explícitas (read / create / update / delete); sin grant (o con la capacidad pedida en false) el MEMBER recibe 403 en esa operación del panel. Ese grant no autoriza App Data ni el plano de aplicación. Aceptar una versión posterior se rechaza (409) si hay instancias activas que no cumplen el schema nuevo; las bajas lógicas no bloquean.
Límite de acceso: operar en un catálogo o instancia tenant requiere una membresía UserCompany activa en esa empresa y se aplican sus roles/grants. El rol Super Admin solo autoriza el catálogo de plataforma; no concede acceso al catálogo ni a los datos de un tenant. X-Company-Id puede seleccionar únicamente una empresa miembro.
Las instancias y relaciones creadas desde el runtime quedan aisladas por environmentId, derivado en servidor después de autorizar proyecto, entorno y release. Las lecturas, escrituras, referencias, joins de consulta y validación de unicidad se limitan a ese entorno; IDs de referencia de otro entorno se rechazan. Los registros anteriores y las operaciones del Entity Manager permanecen en el plano administrativo de empresa.
Conceptos clave
- Dos catálogos: plataforma (
companyIdnulo) y tenant (una empresa). Un tenant nunca ve las definiciones ni los follows de otro. - Ciclo DSL: borrador → validación → versión → publicación. Solo una versión publicada está en vigor. Un borrador no se trata como schema ejecutable.
- Inmutabilidad: una versión publicada no se edita. Un cambio crea una versión nueva; la anterior permanece.
- Follow sin copia: seguir una entidad de plataforma no la copia al catálogo del tenant. Queda un pin a la versión publicada concreta.
- El pin no se mueve cuando el Super Admin publica vN+1. OWNER/ADMIN aceptan esa versión cuando les convenga.
- Fork: copia la versión anclada al catálogo del tenant (publicada, en vigor) y corta el follow. El original de plataforma no cambia. Las versiones posteriores de plataforma no se aplican.
- Retiro de plataforma: Super Admin solo puede retirar una versión global cuando no quedan follows tenant anclados. Si quedan, la operación devuelve 409 genérico sin enumerar ni modificar follows, roles o datos. OWNER/ADMIN debe hacer un fork manual autorizado desde su empresa antes de reintentar.
- Aplicación mínima: el Super Admin publica una aplicación de plataforma que declara entidades. Seguir esa app ancla esas entidades (los mismos pines). Se pueden seguir entidades extra por separado.
- Referencias N:1: un campo
referenceguarda el id de otra instancia. En escritura el destino debe existir en este tenant (o ser instancia de una entidad de plataforma que el tenant sigue). Si falta → 400. Una entidad de plataforma no puede referenciar el catálogo de un tenant. No hay vínculos entre tenants. - Tipos de campo: string, text, integer, decimal, boolean, datetime, enum (lista cerrada), reference (N:1 a otra entidad autorizada), file (referencia a un objeto del espacio de ese tenant; nunca el binario). Un campo string/text puede llevar además un formato semántico del catálogo cerrado
email,urlouuid, que se valida además del tipo estructural (no lo sustituye). - Objeto embebido y lista (Entity IR v2): un campo
object(confields[]) olist(conitems) se guarda en línea en la instancia. Un objeto no es una relación: no admitereferencenifiledentro, nionDelete. Ver «Objetos embebidos y listas». - Campos calculados (Entity IR v3): un campo top-level puede derivarse de campos top-level de la misma entidad con el Canonical Expression IR. El servidor calcula el valor al devolver la instancia; no se persiste y la API rechaza escrituras del cliente. Ver «Campos calculados».
- Relaciones N:N nativas: se declaran en el JSON (
name+ dos entidades +onDelete). No es un campo lista. OWNER/ADMIN asocian y desasocian pares publicados. Si es reflexiva (la misma entidad en ambos lados) exige un rol distinto por lado (p. ej. padre / hijo). - Política de borrado: cada N:1 y cada N:N declara
onDelete:restrict(bloquea si hay orígenes),setNull(deja el campo vacío o quita el vínculo; prohibido si el N:1 es required) ocascade(borra también los orígenes; un ciclo no resoluble se rechaza). La baja lógica (DELETEde instancia) aplica esas políticas:restrict→ 409 y no da de baja. SisetNullocascadetocan varias instancias, todas las escrituras van en una sola transacción (todas o ninguna). - Nombre único por catálogo. Si choca, la API responde 409 con sugerencias no usadas.
- Límites: 50 campos y 10 relaciones por entidad (N:1 + N:N), 50 instancias por página y 200 caracteres de búsqueda. Solo el Super Admin los cambia en Ajustes (
entity_manager_max_fields_per_entity,entity_manager_max_relations_per_entity,entity_manager_max_instances_per_page,entity_manager_max_search_characters): un actor que no sea Super Admin recibe 403 y el máximo vigente se conserva; un valor que no sea entero ≥ 1 se rechaza con 400 (no se restaura el default en silencio). - Consultas: el schema declara qué campos (o combinaciones) son
filterable/sortabley qué campos string/text/enum sonsearchable. El listado filtra por igualdad, rango, contains, in y vacío; ordena por un campo declarado; busca texto a la vez en los buscables; y puede usar campos de entidades relacionadas por N:1 o N:N (customer.name,order_products.sku). Un campo no declarado para ese uso → 400. Unaqvacía se ignora (no coincide con todo). - Permisos: Super Admin gestiona el catálogo de plataforma (incl. retiro). OWNER y ADMIN gestionan el de su empresa, follows, aceptación, fork e instancias sin grant. MEMBER no gestiona definiciones. Para instancias del panel, el OWNER concede un grant por entidad con
read/create/update/delete; la operación solo pasa si esa capacidad está entrue. ADMIN no concede ni revoca grants. - Instancias: solo contra una versión publicada en vigor. Si el tenant tiene la entidad en su catálogo, se usa esa versión publicada; si no, se usa el schema anclado de un follow de plataforma. El
:entityNamede la ruta es case-insensitive. Si la entidad existe pero solo tiene borrador (sin publicada en vigor) → 400. Si el nombre no resuelve a ninguna entidad del catálogo tenant ni a un follow de plataforma → 404. Un borrador no admite escrituras ni listados de instancias. - Validación antes de persistir: tipo, required, unique (simple o compuesto; los vacíos no participan), min/max de longitud o magnitud, patrón de string, formato semántico (
email/url/uuid), y condicionales «si A vale X, B pasa a required o prohibido». - Pattern declarativo acotado: un
patternes un dato del schema, nunca código del tenant. Se rechaza al declarar el campo si supera 200 caracteres o si es susceptible de backtracking catastrófico (repetición anidada del tipo(a+)+, alternancia ambigua del tipo(a|a)+). No se confía en un timeout del motor. Los formatos semánticos son la evolución preferente frente a patrones libres. - Campos extra: se rechazan (no se recortan).
referenceexige que el destino exista en el tenant. - Campo fichero: el valor es la ruta relativa del objeto en el espacio del tenant. Con
object_storage_enabled, la escritura exige un fichero vivo de ese espacio (otro tenant, plataforma, backups o ausente → 400). Si el objeto se borra después,GET/LISTsiguen devolviendo la instancia y listan el campo enbrokenFileFields(no 404). EnPATCH, un campo fichero required o presente en el body exige referencia viva; un optional no tocado puede quedarse roto. Sin el entitlement, el schema con camposfilese puede publicar; en lectura y escritura esos campos se ignoran (se recortan, no dan 400 por estar presentes) ybrokenFileFieldsva vacío. - Identidad: UUID único en el ámbito tenant + entidad;
createdAtyupdatedAtse registran. - Baja lógica:
DELETEmarca la instancia (deletedAt). Desaparece de listados y deGETpor id (404). OWNER/ADMIN pueden restaurarla por id aunque el get público dé 404. Las bajas no participan en unique: se puede crear otra instancia con el mismo valor. Restaurar con ese unique ocupado por una activa → 409. - Aislamiento: un tenant no lee ni escribe instancias de otro. Un get cruzado responde 404 sin filtrar datos.
Endpoints
Todos requieren Authorization: Bearer <token>. space es platform o tenant.
| Método | Ruta | Quién |
|---|---|---|
POST | /entity-manager/:space/definitions | Plataforma: Super Admin. Tenant: miembro activo OWNER/ADMIN |
GET | /entity-manager/:space/definitions | Igual |
GET | /entity-manager/:space/definitions/:id | Igual — 404 si es de otro catálogo |
PATCH | /entity-manager/:space/definitions/:id | Actualiza un borrador; si la última versión está publicada, crea una nueva |
POST | /entity-manager/:space/definitions/:id/publish | Publica el borrador si es válido |
POST | /entity-manager/:space/definitions/:id/versions | Crea un borrador a partir de la versión publicada |
POST | /entity-manager/tenant/follows | OWNER/ADMIN — seguir entidad de plataforma (definitionId o name) |
GET | /entity-manager/tenant/follows | OWNER/ADMIN — pines del tenant |
POST | /entity-manager/tenant/follows/:followId/accept | OWNER/ADMIN — aceptar versión posterior; 409 si instancias activas no cumplen |
POST | /entity-manager/tenant/follows/:followId/fork | OWNER/ADMIN — copiar versión anclada y cortar follow |
POST | /entity-manager/platform/definitions/:id/versions/:version/retire | Super Admin — retirar solo versión global; 409 genérico si quedan follows; no muta relaciones tenant |
POST | /entity-manager/platform/applications | Super Admin — borrador (name, declaredEntities) |
GET | /entity-manager/:space/applications | Plataforma: Super Admin. Tenant: miembro activo OWNER/ADMIN (copias forkeadas) |
GET | /entity-manager/:space/applications/:id | Igual |
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 — retirar solo versión global; 409 genérico si quedan follows; no muta relaciones tenant |
POST | /entity-manager/tenant/application-follows | OWNER/ADMIN — seguir app y anclar entidades declaradas |
GET | /entity-manager/tenant/application-follows | OWNER/ADMIN |
POST | /entity-manager/tenant/application-follows/:followId/accept | OWNER/ADMIN — 409 si instancias activas no cumplen el schema |
GET | /entity-manager/tenant/permissions | OWNER — lista grants de panel (por entidad y capacidades) |
PUT | /entity-manager/tenant/permissions/:userId | OWNER — upsert grant de un MEMBER ({ entity, grant }) |
DELETE | /entity-manager/tenant/permissions/:userId/:entityName | OWNER — revoca el grant de esa entidad — 204 |
DELETE | /entity-manager/tenant/permissions/:userId | OWNER — revoca todos los grants del MEMBER — 204 |
POST | /entity-manager/tenant/entities/:entityName/instances | OWNER/ADMIN, o MEMBER con create en esa entidad — crear instancia ({ payload }); :entityName case-insensitive; solo borrador → 400; desconocida → 404 |
GET | /entity-manager/tenant/entities/:entityName/instances | OWNER/ADMIN, o MEMBER con read — lista paginada { data, total, page, limit }; :entityName case-insensitive; solo borrador → 400; desconocida → 404; omite bajas |
GET | /entity-manager/tenant/entities/:entityName/instances/:instanceId | OWNER/ADMIN, o MEMBER con read — :entityName case-insensitive; solo borrador → 400; desconocida → 404; 404 si falta, está de baja o es de otro tenant; fichero huérfano → 200 + brokenFileFields |
PATCH | /entity-manager/tenant/entities/:entityName/instances/:instanceId | OWNER/ADMIN, o MEMBER con update — fusiona payload y revalida |
DELETE | /entity-manager/tenant/entities/:entityName/instances/:instanceId | OWNER/ADMIN, o MEMBER con delete — baja lógica — 204; restrict → 409 |
POST | /entity-manager/tenant/entities/:entityName/instances/:instanceId/restore | OWNER/ADMIN, o MEMBER con update — restaura — 200; unique ocupado → 409 |
POST | /entity-manager/tenant/entities/:entityName/relations/:relationName/links | OWNER/ADMIN, o MEMBER con update — asociar par N:N ({ leftInstanceId, rightInstanceId }) |
DELETE | /entity-manager/tenant/entities/:entityName/relations/:relationName/links | OWNER/ADMIN, o MEMBER con update — desasociar par — 204 |
POST | /entity-manager/tenant/entities/:entityName/instances/:instanceId/apply-relation-policies | OWNER/ADMIN, o MEMBER con delete — hook de prueba: políticas + hard-remove — 204; restrict → 409 |
Grant de panel (MEMBER)
PUT /entity-manager/tenant/permissions/:userId
Content-Type: application/json
{
"entity": "customers",
"grant": { "read": true, "create": true, "update": false, "delete": false }
}Respuesta 200 con el grant persistido. Upsert por (usuario, entidad). Solo el OWNER concede o revoca; ADMIN → 403. Si el destinatario no es MEMBER de la empresa → 400; si no es miembro → 404.
Con ese grant, el MEMBER puede listar/leer customers y crear instancias; un PATCH o DELETE sobre esa entidad → 403 (capacidad en false). Sin fila para otra entidad → 403 en cualquier operación de esa otra entidad.
DELETE /entity-manager/tenant/permissions/:userId/customers204 — revoca solo el grant de customers. Sin /:entityName se revocan todos los del MEMBER.
Seguir y aceptar
POST /entity-manager/tenant/follows
Content-Type: application/json
{ "name": "ClientePlataforma" }Respuesta 201 con pinnedVersion (la publicada en vigor). El catálogo del tenant no incluye esa definición. Si la plataforma publica v2, pinnedVersion sigue igual hasta:
POST /entity-manager/tenant/follows/:followId/accept
{ "version": 2 }Fork
POST /entity-manager/tenant/follows/:followId/forkCopia la versión anclada como definición propia (inForceVersion = 1, forkedFromDefinitionId apuntando a plataforma) y elimina el follow.
Instancias
POST /entity-manager/tenant/entities/Customer/instances
Content-Type: application/json
{ "payload": { "title": "Acme" } }Respuesta 201 con id (UUID), payload, brokenFileFields (array de nombres de campo fichero cuya referencia falta), createdAt y updatedAt. GET y PATCH usan el mismo id y solo ven instancias activas. Un campo no declarado en el schema → 400. Un reference cuyo destino no existe (o está de baja) → 400. Un file que no está en el espacio del tenant (o apunta a plataforma/backups) → 400. MEMBER sin grant (o sin la capacidad pedida) → 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"}]Respuesta 200 { data, total, page, limit }. Si page se omite, es la primera. limit por encima del máximo vigente → 400. Operadores de filters: eq, gt, gte, lt, lte, contains, in, empty, notEmpty.
DELETE /entity-manager/tenant/entities/Customer/instances/:id204. La instancia desaparece de GET .../instances y GET .../instances/:id responde 404. Restaurar:
POST /entity-manager/tenant/entities/Customer/instances/:id/restore200 y vuelve al listado. Si otra instancia activa ya ocupa un unique → 409.
Formatos semánticos y patrones
Un campo string o text puede declarar un format del catálogo cerrado (email, url, uuid) y/o un pattern, además del tipo estructural. Ambos se validan al escribir instancias:
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]+$" }
]
}
}- Un
formatfuera del catálogo, o en un campo que no seastring/text→ 400. - Un
patterninválido, de más de 200 caracteres o susceptible de backtracking catastrófico ((a+)+,(a|a)+…) → 400 al declarar el campo o al publicar. No se confía en un timeout del motor; losformatson la evolución preferente frente a patrones libres. - Al escribir una instancia, un valor que no cumple el
formato elpatterndeclarados → 400.
Objetos embebidos y listas
Un campo object declara sus propios fields[]; un campo list (list<T>) declara items (string, text, integer, decimal, boolean, datetime, enum u object) y opcionalmente 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 }
]}}
]
}
}- El schema se sella con
irVersion: 2solo si usaobject/list; los schemas anteriores no cambian.irVersion: 1con object/list → 400. reference/filedentro de un objeto o lista,list<list<T>>,arrayyproperties→ 400. Máximo 3 niveles de anidado, 100 elementos por lista, y todos los campos del árbol cuentan contra el límite de campos.- Estos campos (y los embebidos) no admiten
unique,filterable,sortablenisearchable, ni rutascampo.subcampo; sí pueden ser destino de una condicional. - En una instancia, un valor de tipo incorrecto, un campo embebido obligatorio ausente, una clave no declarada dentro del objeto, un elemento inválido o nulo, o una lista fuera de
minItems/maxItems→ 400, con la ruta (address.street,tags[2]). PATCHreemplaza el valor completo del campoobject/listque se envía.
Campos calculados
Un campo top-level puede declarar computed con un nodo del Canonical Expression IR. La expresión puede leer campos top-level de la misma entidad y usar otros campos calculados; los campos inexistentes, rutas anidadas, operadores o aridades inválidos y ciclos se rechazan al validar la definición.
{
"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" }]
}
}
]
}- El schema se sella con
irVersion: 3cuando incluye campos calculados. Los schemas v1/v2 existentes conservan su versión y representación. - El servidor evalúa y valida el resultado contra el tipo y las restricciones declaradas al crear/actualizar, y vuelve a calcularlo en las respuestas de create, update, get y list. El valor derivado no se guarda en
payload; cualquier intento de enviarlo en una escritura → 400. - Solo se admiten dependencias top-level de la misma entidad. Las dependencias a campos
filese rechazan para no eludir el filtrado por entitlement; también se rechazan las dependencias anidadas o entre entidades. Unreferencetop-level puede usarse como dato local (su id), sin resolver datos de la otra entidad. Los campos calculados no pueden tener tiporeferencenifile, porque esos tipos requieren validaciones asíncronas de destino/objeto, ni participar enunique, declaraciones de consulta o reglas condicionales. Se ejecutan solo en servidor.
Relaciones N:N
POST /entity-manager/tenant/entities/Order/relations/order_products/links
Content-Type: application/json
{ "leftInstanceId": "<order-uuid>", "rightInstanceId": "<product-uuid>" }Respuesta 201 con el vínculo. DELETE al mismo path con el mismo cuerpo → 204. Un extremo ausente o de otro tenant → 400 sin filtrar datos ajenos.
Relacionado
- Configuración — máximos de campos, relaciones, página y búsqueda
- Roles y permisos
- Almacenamiento de objetos — espacio de objetos que referencia el tipo de campo fichero