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.

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à

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à

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

Struttura dello schema dell’entità

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

{
  "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:

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

CORRETTO - Metti type e properties al livello superiore:

{
  "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:

{
  "title": {
    "type": "string",
    "description": "Task title"
  }
}

Con formato:

{
  "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:

{
  "status": {
    "type": "string",
    "enum": ["todo", "in_progress", "done"],
    "default": "todo",
    "description": "Current status"
  }
}

Number

{
  "position": {
    "type": "number",
    "description": "Position for ordering"
  }
}

Integer

Solo per numeri interi:

{
  "quantity": {
    "type": "integer",
    "description": "Item quantity",
    "minimum": 0,
    "maximum": 1000
  }
}

Binary

Per dati file/blob:

{
  "attachment": {
    "type": "binary",
    "description": "File attachment"
  }
}

Boolean

{
  "notify_on_change": {
    "type": "boolean",
    "default": true,
    "description": "Enable notifications"
  }
}

Array di stringhe

{
  "labels": {
    "type": "array",
    "items": { "type": "string" },
    "description": "Task labels/tags"
  }
}

Array di oggetti

{
  "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:

{
  "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:

{
  "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:

true - consente a tutti gli utenti (inclusi anonimi/non autenticati)
false - blocca tutti gli utenti
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:

{
  "created_by": "{{user.email}}"
}

2. Verifica condizione utente - Verifica direttamente le proprietà dell’utente usando user_condition:

{
  "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

Esempi RLS

Accesso solo al proprietario:

{
  "created_by": "{{user.email}}"
}

Accesso basato su dipartimento:

{
  "data.department": "{{user.data.department}}"
}

Accesso solo admin:

{
  "user_condition": { "role": "admin" }
}

Configurazione RLS completa:

{
  "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):

{
  "rls": {
    "create": true,
    "read": { "user_condition": { "role": "admin" } },
    "update": { "user_condition": { "role": "admin" } },
    "delete": { "user_condition": { "role": "admin" } }
  }
}

Accesso solo al proprietario:

{
  "rls": {
    "create": true,
    "read": { "created_by": "{{user.email}}" },
    "update": { "created_by": "{{user.email}}" },
    "delete": { "created_by": "{{user.email}}" }
  }
}

Solo utenti loggati:

{
  "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 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:

Usa l’interfaccia della dashboard di Base44 - la dashboard permette di aggiungere più regole per operazione con logica OR
Usa entità separate - dividi i dati in più entità con regole di accesso diverse
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

{
  "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.

npx base44 entities push

Per ulteriori dettagli sul comando push, consulta entities-push.md.

Questa pagina è stata tradotta utilizzando l’IA. Per informazioni più accurate e aggiornate, consulta la versione inglese.

​Creare entità

​Critico: denominazione dei file

​Indice

​Directory delle entità

​Come creare un’entità

​Struttura dello schema dell’entità

​Errore comune: proprietà schema annidata

​Tipi di campo supportati

​String

​String con Enum

​Number

​Integer

​Binary

​Boolean

​Array di stringhe

​Array di oggetti

​Proprietà dei campi

​Esempio completo

​Convenzioni di denominazione

​Relazioni tra entità

​Sicurezza a livello di riga (RLS)

​Operazioni RLS

​Valori dei permessi

​Variabili template

​Attributi integrati dell’entità

​Tipi di regole

​Esempi RLS

​Pattern RLS comuni

​Limitazioni

​Pattern di accesso complessi

​Sicurezza a livello di campo (FLS)

​Operazioni FLS

​Esempio FLS

​Note FLS

​Push delle entità

Creare entità

Critico: denominazione dei file

Indice

Directory delle entità

Come creare un’entità

Struttura dello schema dell’entità

Errore comune: proprietà schema annidata

Tipi di campo supportati

String

String con Enum

Number

Integer

Binary

Boolean

Array di stringhe

Array di oggetti

Proprietà dei campi

Esempio completo

Convenzioni di denominazione

Relazioni tra entità

Sicurezza a livello di riga (RLS)

Operazioni RLS

Valori dei permessi

Variabili template

Attributi integrati dell’entità

Tipi di regole

Esempi RLS

Pattern RLS comuni

Limitazioni

Pattern di accesso complessi

Sicurezza a livello di campo (FLS)

Operazioni FLS

Esempio FLS

Note FLS

Push delle entità