> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Esquemas de entidad

> Define estructuras de datos personalizadas usando un JSON Schema con reglas de validación y tipos de campo

Estás viendo la documentación para desarrolladores

Esta documentación es para desarrolladores que trabajan con la plataforma para desarrolladores de Base44. Para información sobre la gestión de los datos de tu app desde el editor de apps, consulta [Gestionar los datos de la app](https://docs.base44.com/Building-your-app/Managing-your-app-data.md).

Las entidades se definen usando un JSON Schema que describe la estructura de datos y las reglas de validación.

## Estructura básica del esquema

Los esquemas de entidad se definen en archivos JSON en el directorio de entidades de tu proyecto. Por defecto es `base44/entities/`, pero puedes personalizar la ruta en tu [configuración del proyecto](https://docs.base44.com/developers/backend/overview/project-structure.md#config-jsonc). El nombre del archivo determina el nombre de la entidad. Por ejemplo, `Task.json` crea una entidad `Task`.

Aquí tienes una plantilla de esquema de entidad:

```json theme={null}
{
  "name": "my_entity",
  "type": "object",
  "title": "My Entity",
  "description": "Description of what this entity represents",
  "properties": {
    "<field_name>": {
      "type": "<field_type>",
      "<option>": "<value>"
    }
  },
  "required": ["<field_name>"]
}
```

## Campos integrados

Cada registro de entidad incluye automáticamente los siguientes campos. No definas campos con estos nombres en tu esquema.

| Campo | Tipo | Descripción |
| - | - | - |
| `id` | string | Identificador único del registro |
| `created_date` | datetime | Cuándo se creó el registro |
| `updated_date` | datetime | Cuándo se actualizó el registro por última vez |
| `created_by` | string | Email del usuario que creó el registro |
| `created_by_id` | string | ID del usuario que creó el registro |
| `is_deleted` (interno) | boolean | Flag de eliminación lógica |
| `deleted_date` (interno) | datetime | Cuándo se eliminó el registro |
| `is_sample` (interno) | boolean | Si el registro es de datos de muestra |
| `entity_name` (interno) | string | Nombre del tipo de entidad |
| `app_id` (interno) | string | App ID |
| `environment` (interno) | string | `prod` o `dev` |

Los campos internos no se devuelven en las respuestas de la API, pero se pueden referenciar en las [reglas de seguridad](https://docs.base44.com/developers/backend/resources/entities/security.md).

## Campos del esquema

**name** `string`

Identificador en cadena de texto de la entidad.

**type** `string` *required*

Debe ser `"object"`.

**title** `string`

Nombre para mostrar amigable.

**description** `string`

Descripción de lo que representa la entidad.

**properties** `object` *required*

Objeto que contiene las definiciones de tus campos. Cada campo tiene un `type` y reglas
opcionales de validación.

## Tipos de campo

Las entidades admiten varios tipos de campo para definir los distintos tipos de datos que puedes almacenar: `string`, `integer`, `number`, `boolean`, `array` y `object`.
Cada campo dentro de `properties` requiere un `type`. Según el tipo, puedes añadir opciones de validación.

### Campos string

Los campos string admiten estas opciones:

* **`minLength`** / **`maxLength`**: Controlan el número mínimo y máximo de caracteres.
* **`pattern`**: Expresión regular para validación personalizada.
* **`format`**: Formatos predefinidos. Valores admitidos:
  * `"date"`
  * `"date-time"`
  * `"time"`
  * `"email"`
  * `"uri"`
  * `"hostname"`
  * `"ipv4"`
  * `"ipv6"`
  * `"uuid"`
* **`enum`**: Restringe a valores específicos permitidos. Defínelo como un array: `["value1", "value2", "value3"]`.
* **`default`**: Valor predeterminado si no se proporciona ninguno.

### Campos integer

Los campos integer admiten estas opciones:

* **`minimum`** / **`maximum`**: Establecen límites inferior/superior inclusivos.
* **`default`**: Valor predeterminado si no se proporciona ninguno.

### Campos number

Los campos number admiten estas opciones:

* **`minimum`** / **`maximum`**: Establecen límites inferior/superior inclusivos.
* **`default`**: Valor predeterminado si no se proporciona ninguno.

### Campos boolean

Los campos boolean admiten estas opciones:

* **`default`**: Valor predeterminado si no se proporciona ninguno.

### Campos array

Los campos array admiten estas opciones:

* **`items`**: Define el tipo/esquema para los elementos del array.
* **`default`**: Valor de array predeterminado si no se proporciona ninguno.

### Campos object

Los campos object admiten estas opciones:

* **`properties`**: Define los campos dentro del objeto.
* **`required`**: Lista de nombres de propiedades obligatorios.

## Campos obligatorios

Especifica qué campos deben proporcionarse:

```json theme={null}
{
  "required": ["title", "email"]
}
```

## Unicidad

Las entidades de Base44 no admiten restricciones de unicidad. Una propiedad que no forma parte del formato del esquema, como `unique_fields`, se almacena con tu esquema y se ignora.

> [!NOTE]
>
> Para evitar registros duplicados, comprueba si existe un registro en una backend function antes de crear uno nuevo. Una comprobación así reduce la ventana para duplicados pero no la cierra. Para asegurarte de que solo un usuario lo consiga, usa el patrón de reclamación de [actualizaciones concurrentes](#concurrent-updates).

## Actualizaciones concurrentes

Base44 no bloquea registros ni ejecuta transacciones sobre varios registros. Cuando 2 usuarios o procesos cambian los mismos datos a la vez, cada escritura se aplica por separado. Esta sección explica qué actualizaciones son atómicas, cómo reclamar un registro de forma segura y qué esperar de las llamadas que escriben varios registros.

### Reclamar un registro de forma segura

Para asegurarte de que solo un usuario puede reclamar un registro existente, como una tarea o un hueco de reserva, llama a `updateMany()` con el `id` de ese único registro y las condiciones que deben seguir cumpliéndose. La actualización solo se aplica si esas condiciones siguen cumpliéndose en el momento de la escritura. Así, cuando 2 usuarios lo intentan a la vez, solo uno lo consigue. Revisa `updated` en la respuesta para ver si fue el tuyo.

```javascript theme={null}
const result = await base44.entities.Task.updateMany(
  { id: taskId, status: "open" },
  { $set: { status: "claimed", claimed_by: user.email } }
);

if (result.updated === 1) {
  // This user claimed the task.
} else {
  // Someone else claimed it first, or it was no longer open.
}
```

> [!WARNING]
>
> Las condiciones solo se vuelven a comprobar en el momento de la escritura cuando la consulta indica el `id` de un único registro como valor simple. Cualquier otra consulta, incluidos varios ids en `$in` o `$or`, primero encuentra los registros que coinciden y luego los actualiza. Por eso, un registro que cambió entretanto aún puede actualizarse.

### Escribir varios registros

`bulkCreate()`, `bulkUpdate()`, `updateMany()`, `deleteMany()` y `upsert()` no son transacciones. Cada registro se escribe por separado, así que si una llamada falla a medias, los registros ya escritos se quedan escritos. Diseña estas llamadas para que sea seguro volver a ejecutarlas, por ejemplo, filtrando los registros que ya se actualizaron.

Las llamadas concurrentes a `upsert()` con la misma clave pueden crear registros duplicados.

## Ejemplo completo

Aquí tienes un esquema de entidad completo:

```json theme={null}
{
  "name": "Task",
  "type": "object",
  "title": "Task",
  "description": "A task item with priority, due date, and completion status",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "description": {
      "type": "string",
      "maxLength": 1000
    },
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high"],
      "default": "medium"
    },
    "completed": {
      "type": "boolean",
      "default": false
    },
    "due_date": {
      "type": "string",
      "format": "date"
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    },
    "internal_notes": {
      "type": "string",
      "rls": {
        "read": {"user_condition": {"role": "admin"}},
        "write": {"user_condition": {"role": "admin"}}
      }
    }
  },
  "required": ["title"],
  "rls": {
    "create": true,
    "read": {"created_by": "{{user.email}}"},
    "update": {"created_by": "{{user.email}}"},
    "delete": {"created_by": "{{user.email}}"}
  }
}
```

## Desplegar entidades

Después de definir tu esquema de entidad, despliégalo en Base44 usando [`entities push`](https://docs.base44.com/developers/references/cli/commands/entities-push). Las entidades también se despliegan automáticamente cuando ejecutas el comando [`deploy`](https://docs.base44.com/developers/references/cli/commands/deploy) para desplegar todo tu proyecto.

Una vez desplegado, puedes interactuar con tus entidades usando el [módulo `entities` del SDK](https://docs.base44.com/developers/references/sdk/docs/type-aliases/entities). El nombre de la entidad en tu esquema debe coincidir exactamente con cómo accedes a ella en el SDK, incluida la capitalización. Por ejemplo, si tu esquema tiene `"name": "Task"`, debes acceder a ella como `base44.entities.Task.list()`.

Los esquemas de entidad desplegados se pueden visualizar en el panel en la sección **Data**.

## Ver también

* [Esquema de usuario](https://docs.base44.com/developers/backend/resources/entities/user-schema.md): Entidad integrada especial para la autenticación de usuarios
* [Seguridad](https://docs.base44.com/developers/backend/resources/entities/security.md): Configura reglas de seguridad a nivel de fila para entidades
* [Estructura del proyecto](https://docs.base44.com/developers/backend/overview/project-structure.md): Cómo encajan los esquemas de entidad en tu proyecto

> [!NOTE]
>
> Esta página se tradujo con IA. Para información más precisa y actualizada, consulta la [versión en inglés](https://docs.base44.com/index.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.