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

# Creare entità

> Le entità Base44 sono definite localmente nel tuo progetto e poi inviate al backend di Base44.

<Warning>
  Questa pagina fa parte di una skill per agenti IA di programmazione ed è scritta per gli agenti, non per gli umani. Per la documentazione Base44 leggibile dagli umani, consulta la [documentazione per sviluppatori](/developers).
</Warning>

# Creare entità

Le entità Base44 sono definite localmente nel tuo progetto e poi inviate al backend di Base44.

## Critico: denominazione dei file

I file delle entità DEVONO usare la denominazione kebab-case: `{kebab-case-name}.jsonc`

| Nome entità   | Nome file            |
| ------------- | -------------------- |
| `Task`        | `task.jsonc`         |
| `TeamMember`  | `team-member.jsonc`  |
| `ActivityLog` | `activity-log.jsonc` |

SBAGLIATO: `TeamMember.jsonc`, `teamMember.jsonc`
CORRETTO: `team-member.jsonc`

## Indice

* [Creare entità](#creating-entities)
  * [Directory delle entità](#entity-directory)
  * [Come creare un'entità](#how-to-create-an-entity)
  * [Struttura dello schema dell'entità](#entity-schema-structure)
  * [Tipi di campo supportati](#supported-field-types)
  * [Proprietà dei campi](#field-properties)
  * [Esempio completo](#complete-example)
  * [Convenzioni di denominazione](#naming-conventions)
  * [Relazioni tra entità](#relationships-between-entities)
  * [Sicurezza a livello di riga (RLS)](#row-level-security-rls)
  * [Sicurezza a livello di campo (FLS)](#field-level-security-fls)
  * [Push delle entità](#pushing-entities)

## Directory delle entità

Tutte le definizioni delle entità devono essere posizionate nella cartella `base44/entities/` nella directory principale del tuo progetto. Ogni entità è definita nel proprio file `.jsonc`.

Struttura di esempio:

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

## Come creare un'entità

1. Crea un nuovo file `.jsonc` nella directory `base44/entities/`
2. Definisci lo schema dell'entità seguendo la struttura qui sotto
3. Invia le modifiche a Base44 usando la CLI

## Struttura dello schema dell'entità

Ogni file di entità segue una struttura simile a JSON Schema:

```jsonc theme={null}
{
  "name": "EntityName",       // PascalCase entity name
  "type": "object",           // Always "object"
  "properties": {
    // Define your fields here
  },
  "required": ["field1"]      // Array of required field names
}
```

### Errore comune: proprietà schema annidata

**SBAGLIATO** - NON avvolgere le proprietà in un oggetto `schema`:

```jsonc theme={null}
{
  "name": "Task",
  "description": "A task entity",
  "schema": {                    // ❌ WRONG - don't use nested "schema"
    "type": "object",
    "properties": { ... }
  }
}
```

**CORRETTO** - Metti `type` e `properties` al livello superiore:

```jsonc theme={null}
{
  "name": "Task",
  "description": "A task entity",
  "type": "object",              // ✅ CORRECT - top level
  "properties": { ... }          // ✅ CORRECT - top level
}
```

Questo è un errore comune che causerà errori "Invalid schema: Schema must have a 'type' field" quando si inviano le entità.

## Tipi di campo supportati

### String

Campo di testo di base:

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

Con formato:

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

Formati disponibili: `date`, `date-time`, `time`, `email`, `uri`, `hostname`, `ipv4`, `ipv6`, `uuid`, `file`, `regex`, `richtext`

### String con Enum

Limitato a valori specifici:

```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 per numeri interi:

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

### Binary

Per dati file/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 di stringhe

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

### Array di oggetti

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

## Proprietà dei campi

| Proprietà     | Descrizione                                                                                                                           |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `type`        | Tipo di dato: `string`, `number`, `integer`, `boolean`, `array`, `object`, `binary`                                                   |
| `description` | Descrizione leggibile del campo                                                                                                       |
| `enum`        | Array di valori consentiti (per stringhe)                                                                                             |
| `enumNames`   | Etichette leggibili per i valori enum (stesso ordine di `enum`)                                                                       |
| `default`     | Valore predefinito quando non fornito                                                                                                 |
| `format`      | Suggerimento di formato: `date`, `date-time`, `time`, `email`, `uri`, `hostname`, `ipv4`, `ipv6`, `uuid`, `file`, `regex`, `richtext` |
| `items`       | Schema per gli elementi dell'array                                                                                                    |
| `properties`  | Proprietà annidate per i tipi oggetto                                                                                                 |
| `$ref`        | Riferimento a un'altra definizione di schema                                                                                          |
| `minLength`   | Lunghezza minima della stringa                                                                                                        |
| `maxLength`   | Lunghezza massima della stringa                                                                                                       |
| `pattern`     | Pattern regex per la validazione della stringa                                                                                        |
| `minimum`     | Valore minimo per i numeri                                                                                                            |
| `maximum`     | Valore massimo per i numeri                                                                                                           |
| `rls`         | Regole di sicurezza a livello di campo (vedi sezione Sicurezza a livello di campo)                                                    |

## Esempio completo

Ecco una definizione completa di entità per un 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"]
}
```

## Convenzioni di denominazione

* **Nome entità**: usa PascalCase con solo caratteri alfanumerici (ad es. `Task`, `TeamMember`, `ActivityLog`)
  * Deve corrispondere al pattern: `/^[a-zA-Z0-9]+$/`
  * Validi: `Task`, `TeamMember`, `Order123`
  * Non validi: `Team_Member`, `Team-Member`, `Team Member`
* **Nome file**: usa kebab-case corrispondente all'entità (ad es. `task.jsonc`, `team-member.jsonc`, `activity-log.jsonc`)
* **Nomi dei campi**: usa snake\_case (ad es. `board_id`, `user_email`, `due_date`)

## Relazioni tra entità

Per creare relazioni tra entità, usa campi di riferimento ID:

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

## Sicurezza a livello di riga (RLS)

La sicurezza a livello di riga (RLS) controlla a quali record gli utenti possono accedere in base alla loro identità e attributi. Le regole RLS sono definite per entità nel campo `rls` dello schema.

**Importante:** se non è definita alcuna RLS, tutti i record sono accessibili a tutti gli utenti.

### Operazioni RLS

RLS supporta cinque operazioni:

| Operazione | Descrizione                                               |
| ---------- | --------------------------------------------------------- |
| `create`   | Controlla chi può aggiungere nuovi record                 |
| `read`     | Controlla chi può visualizzare i record                   |
| `update`   | Controlla chi può modificare i record                     |
| `delete`   | Controlla chi può rimuovere i record                      |
| `write`    | Abbreviazione per `create`, `update` e `delete` combinati |

### Valori dei permessi

Ogni operazione accetta uno dei seguenti valori:

1. **`true`** - consente a tutti gli utenti (inclusi anonimi/non autenticati)
2. **`false`** - blocca tutti gli utenti
3. **Oggetto condizione** - consente agli utenti che corrispondono alla condizione

### Variabili template

Usa variabili template per referenziare gli attributi dell'utente corrente:

| Template                   | Descrizione                                          |
| -------------------------- | ---------------------------------------------------- |
| `{{user.id}}`              | L'ID dell'utente                                     |
| `{{user.email}}`           | L'email dell'utente                                  |
| `{{user.role}}`            | Il ruolo dell'utente                                 |
| `{{user.data.field_name}}` | Campo personalizzato dall'oggetto `data` dell'utente |

### Attributi integrati dell'entità

Ogni record di entità ha questi attributi integrati disponibili per le regole RLS:

| Attributo      | Descrizione                                                     |
| -------------- | --------------------------------------------------------------- |
| `id`           | Identificatore univoco del record                               |
| `created_date` | Timestamp di quando il record è stato creato                    |
| `updated_date` | Timestamp di quando il record è stato aggiornato l'ultima volta |
| `created_by`   | Email dell'utente che ha creato il record                       |

### Tipi di regole

Ci sono due tipi di condizioni che puoi usare:

**1. Confronto entità-utente** - Confronta i campi del record con i valori dell'utente corrente:

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

**2. Verifica condizione utente** - Verifica direttamente le proprietà dell'utente usando `user_condition`:

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

**Note importanti:**

* `user_condition` supporta solo **uguaglianza semplice** (ad es. `{ "role": "admin" }`)
* **Il filtro sui campi dell'entità richiede il prefisso `data.`:** usa `{ "data.fieldname": value }` per filtrare per valori dei campi dell'entità
* Per confronti sui campi `data.*`, puoi usare gli operatori: `$in`, `$nin`, `$ne`, `$all`
* Gli operatori logici `$or`, `$and`, `$nor` sono disponibili per combinare condizioni

⚠️ **Per pattern RLS avanzati ed esempi, consulta [rls-examples.md](https://docs.base44.com/developers/skills/base44-cli/references/rls-examples.md)**

### Esempi RLS

**Accesso solo al proprietario:**

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

**Accesso basato su dipartimento:**

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

**Accesso solo admin:**

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

**Configurazione 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}}" }
  }
}
```

### Pattern RLS comuni

**Creazione pubblica, gestione solo admin (ad es. moduli di contatto, liste di attesa):**

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

**Accesso solo al proprietario:**

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

**Solo utenti loggati:**

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

### Limitazioni

* **user\_condition solo per uguaglianza:** `user_condition` supporta solo la corrispondenza esatta (ad es. `{ "role": "admin" }`) - nessun operatore
* **Nessun operatore di confronto su user\_condition:** `$gt`, `$lt`, `$regex`, `$expr`, `$where` NON sono supportati per le condizioni utente
* **Nessun template profondamente annidato:** template come `{{user.data.profile.department}}` potrebbero non funzionare

**Operatori supportati:**

* **Operatori logici:** `$or`, `$and`, `$nor` per combinare più condizioni
* **Operatori sui campi (solo per campi `data.*`):** `$in`, `$nin`, `$ne`, `$all`
* **Filtro sui campi dell'entità:** usa il prefisso `data.` per filtrare per valori dei campi dell'entità (ad es. `{ "data.status": "published" }` o `{ "data.completed": true }`)

⚠️ **Consulta [rls-examples.md](https://docs.base44.com/developers/skills/base44-cli/references/rls-examples.md) per pattern ed esempi RLS completi**

### Pattern di accesso complessi

Per pattern di accesso complessi che richiedono più condizioni (ad es. "proprietario O admin"), hai due opzioni:

1. **Usa l'interfaccia della dashboard di Base44** - la dashboard permette di aggiungere più regole per operazione con logica OR
2. **Usa entità separate** - dividi i dati in più entità con regole di accesso diverse
3. **Usa funzioni backend** - implementa una logica di accesso personalizzata nelle funzioni backend

## Sicurezza a livello di campo (FLS)

La sicurezza a livello di campo ti permette di controllare l'accesso ai singoli campi all'interno di un'entità. Le regole FLS sono definite all'interno dello schema di ogni campo usando la proprietà `rls`.

### Operazioni FLS

FLS supporta le stesse operazioni di RLS a livello di entità:

| Operazione | Descrizione                                                 |
| ---------- | ----------------------------------------------------------- |
| `create`   | Controlla chi può impostare questo campo quando crea record |
| `read`     | Controlla chi può visualizzare questo campo                 |
| `update`   | Controlla chi può modificare questo campo                   |
| `delete`   | Controlla chi può cancellare questo campo                   |
| `write`    | Abbreviazione per `create`, `update` e `delete` combinati   |

### Esempio 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"]
}
```

In questo esempio, solo gli utenti con il ruolo `hr` possono leggere o aggiornare il campo `salary`. Tutti gli utenti con accesso all'entità possono leggere/aggiornare gli altri campi.

### Note FLS

* Se non è definita alcuna RLS a livello di campo, il campo eredita le regole RLS a livello di entità
* Le regole FLS seguono lo stesso formato di condizioni delle RLS a livello di entità
* Usa FLS per campi sensibili come stipendio, SSN o note interne

## Push delle entità

Il comando `entities push` invierà tutte le entità che esistono nella cartella `base44/entities`.

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

Per ulteriori dettagli sul comando push, consulta [entities-push.md](https://docs.base44.com/developers/skills/base44-cli/references/entities-push.md).

<Note>Questa pagina è stata tradotta utilizzando l'IA. Per informazioni più accurate e aggiornate, consulta la [versione inglese](/). </Note>