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

# Crear entidades

> Las entidades de Base44 se definen localmente en tu proyecto y luego se envían al backend de Base44.

<Warning>
  Esta página es parte de una habilidad de agente de codificación con IA y está escrita para agentes, no para humanos. Para la documentación de Base44 legible por humanos, consulta la [documentación para desarrolladores](/developers).
</Warning>

# Crear entidades

Las entidades de Base44 se definen localmente en tu proyecto y luego se envían al backend de Base44.

## Crítico: nomenclatura de archivos

Los archivos de entidad DEBEN usar nomenclatura kebab-case: `{kebab-case-name}.jsonc`

| Nombre de entidad | Nombre de archivo    |
| ----------------- | -------------------- |
| `Task`            | `task.jsonc`         |
| `TeamMember`      | `team-member.jsonc`  |
| `ActivityLog`     | `activity-log.jsonc` |

INCORRECTO: `TeamMember.jsonc`, `teamMember.jsonc`
CORRECTO: `team-member.jsonc`

## Directorio de entidades

Todas las definiciones de entidad deben colocarse en la carpeta `base44/entities/` en la raíz de tu proyecto. Cada entidad se define en su propio archivo `.jsonc`.

Estructura de ejemplo:

```
my-app/
  base44/
    entities/
      user.jsonc
      product.jsonc
      order.jsonc
```

## Cómo crear una entidad

1. Crea un nuevo archivo `.jsonc` en el directorio `base44/entities/`
2. Define el esquema de tu entidad siguiendo la estructura a continuación
3. Envía los cambios a Base44 usando la CLI

## Estructura del esquema de entidad

Cada archivo de entidad sigue una estructura similar a JSON Schema:

```jsonc theme={null}
{
  "name": "EntityName",       // Nombre de entidad en PascalCase
  "type": "object",           // Siempre "object"
  "properties": {
    // Define tus campos aquí
  },
  "required": ["field1"]      // Array de nombres de campos requeridos
}
```

### Error común: propiedad de esquema anidada

**INCORRECTO** - NO envuelvas las propiedades en un objeto `schema`:

```jsonc theme={null}
{
  "name": "Task",
  "description": "A task entity",
  "schema": {                    // ❌ INCORRECTO - no uses "schema" anidado
    "type": "object",
    "properties": { ... }
  }
}
```

**CORRECTO** - Coloca `type` y `properties` en el nivel superior:

```jsonc theme={null}
{
  "name": "Task",
  "description": "A task entity",
  "type": "object",              // ✅ CORRECTO - nivel superior
  "properties": { ... }          // ✅ CORRECTO - nivel superior
}
```

Este es un error común que causará errores "Invalid schema: Schema must have a 'type' field" al enviar entidades.

## Tipos de campo admitidos

### String

Campo de texto básico:

```jsonc theme={null}
{
  "title": {
    "type": "string",
    "description": "Task title"
  }
}
```

Con formato:

```jsonc theme={null}
{
  "due_date": {
    "type": "string",
    "format": "date",
    "description": "Due date"
  }
}
```

Formatos disponibles: `date`, `date-time`, `time`, `email`, `uri`, `hostname`, `ipv4`, `ipv6`, `uuid`, `file`, `regex`, `richtext`

### String con Enum

Restringido a valores específicos:

```jsonc theme={null}
{
  "status": {
    "type": "string",
    "enum": ["todo", "in_progress", "done"],
    "default": "todo",
    "description": "Current status"
  }
}
```

### Number

```jsonc theme={null}
{
  "position": {
    "type": "number",
    "description": "Position for ordering"
  }
}
```

### Integer

Solo para números enteros:

```jsonc theme={null}
{
  "quantity": {
    "type": "integer",
    "description": "Item quantity",
    "minimum": 0,
    "maximum": 1000
  }
}
```

### Binary

Para datos de archivo/blob:

```jsonc theme={null}
{
  "attachment": {
    "type": "binary",
    "description": "File attachment"
  }
}
```

### Boolean

```jsonc theme={null}
{
  "notify_on_change": {
    "type": "boolean",
    "default": true,
    "description": "Enable notifications"
  }
}
```

### Array de Strings

```jsonc theme={null}
{
  "labels": {
    "type": "array",
    "items": { "type": "string" },
    "description": "Task labels/tags"
  }
}
```

### Array de objetos

```jsonc theme={null}
{
  "attachments": {
    "type": "array",
    "description": "File attachments",
    "items": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "url": { "type": "string" },
        "type": { "type": "string" }
      }
    }
  }
}
```

## Propiedades de campo

| Propiedad     | Descripción                                                                                                                         |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `type`        | Tipo de dato: `string`, `number`, `integer`, `boolean`, `array`, `object`, `binary`                                                 |
| `description` | Descripción legible del campo                                                                                                       |
| `enum`        | Array de valores permitidos (para strings)                                                                                          |
| `enumNames`   | Etiquetas legibles para valores de enum (mismo orden que `enum`)                                                                    |
| `default`     | Valor predeterminado cuando no se proporciona                                                                                       |
| `format`      | Sugerencia de formato: `date`, `date-time`, `time`, `email`, `uri`, `hostname`, `ipv4`, `ipv6`, `uuid`, `file`, `regex`, `richtext` |
| `items`       | Esquema para elementos de array                                                                                                     |
| `properties`  | Propiedades anidadas para tipos de objeto                                                                                           |
| `$ref`        | Referencia a otra definición de esquema                                                                                             |
| `minLength`   | Longitud mínima de string                                                                                                           |
| `maxLength`   | Longitud máxima de string                                                                                                           |
| `pattern`     | Patrón regex para validación de string                                                                                              |
| `minimum`     | Valor mínimo para números                                                                                                           |
| `maximum`     | Valor máximo para números                                                                                                           |
| `rls`         | Reglas de seguridad a nivel de campo (ver sección Seguridad a nivel de campo)                                                       |

## Ejemplo completo

Aquí hay una definición completa de entidad para una Task:

```jsonc theme={null}
{
  "name": "Task",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Task title"
    },
    "description": {
      "type": "string",
      "description": "Task description"
    },
    "status": {
      "type": "string",
      "enum": ["todo", "in_progress", "done"],
      "default": "todo",
      "description": "Current status of the task"
    },
    "board_id": {
      "type": "string",
      "description": "Board this task belongs to"
    },
    "assignee_email": {
      "type": "string",
      "description": "Email of assigned user"
    },
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high"],
      "default": "medium",
      "description": "Task priority"
    },
    "due_date": {
      "type": "string",
      "format": "date",
      "description": "Due date"
    },
    "labels": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Task labels/tags"
    }
  },
  "required": ["title"]
}
```

## Convenciones de nomenclatura

* **Nombre de entidad**: Usa PascalCase solo con caracteres alfanuméricos (por ejemplo, `Task`, `TeamMember`, `ActivityLog`)
  * Debe coincidir con el patrón: `/^[a-zA-Z0-9]+$/`
  * Válido: `Task`, `TeamMember`, `Order123`
  * Inválido: `Team_Member`, `Team-Member`, `Team Member`
* **Nombre de archivo**: Usa kebab-case coincidiendo con la entidad (por ejemplo, `task.jsonc`, `team-member.jsonc`, `activity-log.jsonc`)
* **Nombres de campo**: Usa snake\_case (por ejemplo, `board_id`, `user_email`, `due_date`)

## Relaciones entre entidades

Para crear relaciones entre entidades, usa campos de referencia de ID:

```jsonc theme={null}
{
  "board_id": {
    "type": "string",
    "description": "Board this task belongs to"
  },
  "team_id": {
    "type": "string",
    "description": "Associated team ID"
  }
}
```

## Seguridad a nivel de fila (RLS)

La seguridad a nivel de fila (RLS) controla qué registros pueden acceder los usuarios según su identidad y atributos. Las reglas RLS se definen por entidad dentro del campo `rls` del esquema.

**Importante:** Si no se define RLS, todos los registros son accesibles para todos los usuarios.

### Operaciones RLS

RLS admite cinco operaciones:

| Operación | Descripción                                               |
| --------- | --------------------------------------------------------- |
| `create`  | Controla quién puede añadir nuevos registros              |
| `read`    | Controla quién puede ver registros                        |
| `update`  | Controla quién puede modificar registros                  |
| `delete`  | Controla quién puede eliminar registros                   |
| `write`   | Abreviatura para `create`, `update` y `delete` combinados |

### Valores de permiso

Cada operación acepta uno de los siguientes valores:

1. **`true`** - Permitir todos los usuarios (incluidos anónimos/no autenticados)
2. **`false`** - Bloquear todos los usuarios
3. **Objeto de condición** - Permitir usuarios que coincidan con la condición

### Variables de plantilla

Usa variables de plantilla para hacer referencia a los atributos del usuario actual:

| Plantilla                  | Descripción                                       |
| -------------------------- | ------------------------------------------------- |
| `{{user.id}}`              | El ID del usuario                                 |
| `{{user.email}}`           | El correo del usuario                             |
| `{{user.role}}`            | El rol del usuario                                |
| `{{user.data.field_name}}` | Campo personalizado del objeto `data` del usuario |

### Atributos integrados de entidad

Cada registro de entidad tiene estos atributos integrados disponibles para reglas RLS:

| Atributo       | Descripción                                                    |
| -------------- | -------------------------------------------------------------- |
| `id`           | Identificador único del registro                               |
| `created_date` | Marca de tiempo cuando se creó el registro                     |
| `updated_date` | Marca de tiempo cuando se actualizó el registro por última vez |
| `created_by`   | Correo del usuario que creó el registro                        |

### Tipos de regla

Hay dos tipos de condición que puedes usar:

**1. Comparación de entidad a usuario** - Compara campos de registro con los valores del usuario actual:

```jsonc theme={null}
{
  "created_by": "{{user.email}}"
}
```

**2. Comprobación de condición de usuario** - Comprueba las propiedades del usuario directamente usando `user_condition`:

```jsonc theme={null}
{
  "user_condition": { "role": "admin" }
}
```

**Notas importantes:**

* `user_condition` solo admite **igualdad simple** (por ejemplo, `{ "role": "admin" }`)
* **El filtrado de campo de entidad requiere el prefijo `data.`:** Usa `{ "data.fieldname": value }` para filtrar por valores de campo de entidad
* Para comparaciones de campos `data.*`, puedes usar operadores: `$in`, `$nin`, `$ne`, `$all`
* Los operadores lógicos `$or`, `$and`, `$nor` están disponibles para combinar condiciones

⚠️ **Para patrones RLS avanzados y ejemplos, consulta [rls-examples.md](https://docs.base44.com/developers/skills/base44-cli/references/rls-examples.md)**

### Ejemplos de RLS

**Acceso solo del propietario:**

```jsonc theme={null}
{
  "created_by": "{{user.email}}"
}
```

**Acceso basado en departamento:**

```jsonc theme={null}
{
  "data.department": "{{user.data.department}}"
}
```

**Acceso solo de administrador:**

```jsonc theme={null}
{
  "user_condition": { "role": "admin" }
}
```

**Configuración RLS completa:**

```jsonc theme={null}
{
  "name": "Task",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Task title"
    },
    "status": {
      "type": "string",
      "enum": ["todo", "in_progress", "done"],
      "default": "todo"
    }
  },
  "required": ["title"],
  "rls": {
    "create": true,
    "read": { "created_by": "{{user.email}}" },
    "update": { "created_by": "{{user.email}}" },
    "delete": { "created_by": "{{user.email}}" }
  }
}
```

### Patrones RLS comunes

**Creación pública, gestión solo de administrador (por ejemplo, formularios de contacto, listas de espera):**

```jsonc theme={null}
{
  "rls": {
    "create": true,
    "read": { "user_condition": { "role": "admin" } },
    "update": { "user_condition": { "role": "admin" } },
    "delete": { "user_condition": { "role": "admin" } }
  }
}
```

**Acceso solo del propietario:**

```jsonc theme={null}
{
  "rls": {
    "create": true,
    "read": { "created_by": "{{user.email}}" },
    "update": { "created_by": "{{user.email}}" },
    "delete": { "created_by": "{{user.email}}" }
  }
}
```

**Solo usuarios registrados:**

```jsonc theme={null}
{
  "rls": {
    "create": { "user_condition": { "id": "{{user.id}}" } },
    "read": true,
    "update": { "created_by": "{{user.email}}" },
    "delete": { "created_by": "{{user.email}}" }
  }
}
```

### Limitaciones

* **user\_condition es solo igualdad:** `user_condition` solo admite coincidencia exacta (por ejemplo, `{ "role": "admin" }`) - sin operadores
* **Sin operadores de comparación en user\_condition:** `$gt`, `$lt`, `$regex`, `$expr`, `$where` NO están admitidos para condiciones de usuario
* **Sin plantillas profundamente anidadas:** Las plantillas como `{{user.data.profile.department}}` pueden no funcionar

**Operadores admitidos:**

* **Operadores lógicos:** `$or`, `$and`, `$nor` para combinar múltiples condiciones
* **Operadores de campo (solo para campos `data.*`):** `$in`, `$nin`, `$ne`, `$all`
* **Filtrado de campo de entidad:** Usa el prefijo `data.` para filtrar por valores de campo de entidad (por ejemplo, `{ "data.status": "published" }` o `{ "data.completed": true }`)

⚠️ **Consulta [rls-examples.md](https://docs.base44.com/developers/skills/base44-cli/references/rls-examples.md) para patrones y ejemplos RLS completos**

### Patrones de acceso complejos

Para patrones de acceso complejos que requieren múltiples condiciones (por ejemplo, "propietario O administrador"), tienes dos opciones:

1. **Usar la UI del panel de Base44** - El panel permite añadir múltiples reglas por operación con lógica OR
2. **Usar entidades separadas** - Divide los datos en múltiples entidades con diferentes reglas de acceso
3. **Usar funciones de backend** - Implementa lógica de acceso personalizada en funciones de backend

## Seguridad a nivel de campo (FLS)

La seguridad a nivel de campo te permite controlar el acceso a campos individuales dentro de una entidad. Las reglas FLS se definen dentro del esquema de cada campo usando la propiedad `rls`.

### Operaciones FLS

FLS admite las mismas operaciones que RLS a nivel de entidad:

| Operación | Descripción                                                   |
| --------- | ------------------------------------------------------------- |
| `create`  | Controla quién puede establecer este campo al crear registros |
| `read`    | Controla quién puede ver este campo                           |
| `update`  | Controla quién puede modificar este campo                     |
| `delete`  | Controla quién puede borrar este campo                        |
| `write`   | Abreviatura para `create`, `update` y `delete` combinados     |

### Ejemplo de FLS

```jsonc theme={null}
{
  "name": "Employee",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Employee name"
    },
    "salary": {
      "type": "number",
      "description": "Employee salary",
      "rls": {
        "read": { "user_condition": { "role": "hr" } },
        "update": { "user_condition": { "role": "hr" } }
      }
    },
    "department": {
      "type": "string",
      "description": "Department name"
    }
  },
  "required": ["name"]
}
```

En este ejemplo, solo los usuarios con el rol `hr` pueden leer o actualizar el campo `salary`. Todos los usuarios con acceso a la entidad pueden leer/actualizar otros campos.

### Notas de FLS

* Si no se define RLS a nivel de campo, el campo hereda las reglas RLS a nivel de entidad
* Las reglas FLS siguen el mismo formato de condición que RLS a nivel de entidad
* Usa FLS para campos sensibles como salario, SSN o notas internas

## Enviar entidades

El comando `entities push` enviará todas las entidades que existen en la carpeta `base44/entities`.

```bash theme={null}
npx base44 entities push
```

Para más detalles sobre el comando push, consulta [entities-push.md](https://docs.base44.com/developers/skills/base44-cli/references/entities-push.md).

<Note>Esta página fue traducida usando IA. Para obtener la información más precisa y actualizada, consulta la [versión en inglés](/).</Note>