Skip to content

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 (companyId nulo) 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 reference guarda 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, url o uuid, que se valida además del tipo estructural (no lo sustituye).
  • Objeto embebido y lista (Entity IR v2): un campo object (con fields[]) o list (con items) se guarda en línea en la instancia. Un objeto no es una relación: no admite reference ni file dentro, ni onDelete. 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) o cascade (borra también los orígenes; un ciclo no resoluble se rechaza). La baja lógica (DELETE de instancia) aplica esas políticas: restrict → 409 y no da de baja. Si setNull o cascade tocan 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 / sortable y qué campos string/text/enum son searchable. 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. Una q vací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á en true. 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 :entityName de 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 pattern es 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). reference exige 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/LIST siguen devolviendo la instancia y listan el campo en brokenFileFields (no 404). En PATCH, 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 campos file se puede publicar; en lectura y escritura esos campos se ignoran (se recortan, no dan 400 por estar presentes) y brokenFileFields va vacío.
  • Identidad: UUID único en el ámbito tenant + entidad; createdAt y updatedAt se registran.
  • Baja lógica: DELETE marca la instancia (deletedAt). Desaparece de listados y de GET por 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étodoRutaQuién
POST/entity-manager/:space/definitionsPlataforma: Super Admin. Tenant: miembro activo OWNER/ADMIN
GET/entity-manager/:space/definitionsIgual
GET/entity-manager/:space/definitions/:idIgual — 404 si es de otro catálogo
PATCH/entity-manager/:space/definitions/:idActualiza un borrador; si la última versión está publicada, crea una nueva
POST/entity-manager/:space/definitions/:id/publishPublica el borrador si es válido
POST/entity-manager/:space/definitions/:id/versionsCrea un borrador a partir de la versión publicada
POST/entity-manager/tenant/followsOWNER/ADMIN — seguir entidad de plataforma (definitionId o name)
GET/entity-manager/tenant/followsOWNER/ADMIN — pines del tenant
POST/entity-manager/tenant/follows/:followId/acceptOWNER/ADMIN — aceptar versión posterior; 409 si instancias activas no cumplen
POST/entity-manager/tenant/follows/:followId/forkOWNER/ADMIN — copiar versión anclada y cortar follow
POST/entity-manager/platform/definitions/:id/versions/:version/retireSuper Admin — retirar solo versión global; 409 genérico si quedan follows; no muta relaciones tenant
POST/entity-manager/platform/applicationsSuper Admin — borrador (name, declaredEntities)
GET/entity-manager/:space/applicationsPlataforma: Super Admin. Tenant: miembro activo OWNER/ADMIN (copias forkeadas)
GET/entity-manager/:space/applications/:idIgual
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 — retirar solo versión global; 409 genérico si quedan follows; no muta relaciones tenant
POST/entity-manager/tenant/application-followsOWNER/ADMIN — seguir app y anclar entidades declaradas
GET/entity-manager/tenant/application-followsOWNER/ADMIN
POST/entity-manager/tenant/application-follows/:followId/acceptOWNER/ADMIN — 409 si instancias activas no cumplen el schema
GET/entity-manager/tenant/permissionsOWNER — lista grants de panel (por entidad y capacidades)
PUT/entity-manager/tenant/permissions/:userIdOWNER — upsert grant de un MEMBER ({ entity, grant })
DELETE/entity-manager/tenant/permissions/:userId/:entityNameOWNER — revoca el grant de esa entidad — 204
DELETE/entity-manager/tenant/permissions/:userIdOWNER — revoca todos los grants del MEMBER — 204
POST/entity-manager/tenant/entities/:entityName/instancesOWNER/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/instancesOWNER/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/:instanceIdOWNER/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/:instanceIdOWNER/ADMIN, o MEMBER con update — fusiona payload y revalida
DELETE/entity-manager/tenant/entities/:entityName/instances/:instanceIdOWNER/ADMIN, o MEMBER con delete — baja lógica — 204; restrict → 409
POST/entity-manager/tenant/entities/:entityName/instances/:instanceId/restoreOWNER/ADMIN, o MEMBER con update — restaura — 200; unique ocupado → 409
POST/entity-manager/tenant/entities/:entityName/relations/:relationName/linksOWNER/ADMIN, o MEMBER con update — asociar par N:N ({ leftInstanceId, rightInstanceId })
DELETE/entity-manager/tenant/entities/:entityName/relations/:relationName/linksOWNER/ADMIN, o MEMBER con update — desasociar par — 204
POST/entity-manager/tenant/entities/:entityName/instances/:instanceId/apply-relation-policiesOWNER/ADMIN, o MEMBER con delete — hook de prueba: políticas + hard-remove — 204; restrict → 409

Grant de panel (MEMBER) ​

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

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

204 — revoca solo el grant de customers. Sin /:entityName se revocan todos los del MEMBER.

Seguir y aceptar ​

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

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

Fork ​

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

Copia la versión anclada como definición propia (inForceVersion = 1, forkedFromDefinitionId apuntando a plataforma) y elimina el follow.

Instancias ​

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

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"}]

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.

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

204. La instancia desaparece de GET .../instances y GET .../instances/:id responde 404. Restaurar:

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

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

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]+$" }
    ]
  }
}
  • Un format fuera del catálogo, o en un campo que no sea string/text → 400.
  • Un pattern invá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; los format son la evolución preferente frente a patrones libres.
  • Al escribir una instancia, un valor que no cumple el format o el pattern declarados → 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:

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 }
      ]}}
    ]
  }
}
  • El schema se sella con irVersion: 2 solo si usa object/list; los schemas anteriores no cambian. irVersion: 1 con object/list → 400.
  • reference/file dentro de un objeto o lista, list<list<T>>, array y properties → 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, sortable ni searchable, ni rutas campo.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]).
  • PATCH reemplaza el valor completo del campo object/list que 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.

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" }]
      }
    }
  ]
}
  • El schema se sella con irVersion: 3 cuando 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 file se rechazan para no eludir el filtrado por entitlement; también se rechazan las dependencias anidadas o entre entidades. Un reference top-level puede usarse como dato local (su id), sin resolver datos de la otra entidad. Los campos calculados no pueden tener tipo reference ni file, porque esos tipos requieren validaciones asíncronas de destino/objeto, ni participar en unique, declaraciones de consulta o reglas condicionales. Se ejecutan solo en servidor.

Relaciones N:N ​

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