Entity Schemas

Define custom data structures using a JSON Schema with validation rules and field types

You’re viewing developer documentation

This documentation is for developers working with the Base44 developer platform. For information about managing your app data using the app editor, see Managing app data.

Entities are defined using a JSON Schema that describes the data structure and validation rules.

Basic schema structure

Entity schemas are defined in JSON files in your project’s entities directory. By default, this is base44/entities/, but you can customize the path in your project configuration. The filename determines the entity name. For example, Task.json creates a Task entity.

Here’s an entity schema template:

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

Built-in fields

Every entity record automatically includes the following fields. Don’t define fields with these names in your schema.

Field	Type	Description
id	string	Unique identifier for the record
created_date	datetime	When the record was created
updated_date	datetime	When the record was last updated
created_by	string	Email of the user who created the record
created_by_id	string	ID of the user who created the record
is_deleted (internal)	boolean	Soft delete flag
deleted_date (internal)	datetime	When the record was deleted
is_sample (internal)	boolean	Whether the record is sample data
entity_name (internal)	string	Name of the entity type
app_id (internal)	string	App ID
environment (internal)	string	Either prod or dev

Internal fields aren’t returned in API responses but can be referenced in security rules.

Schema fields

name · string

String identifier for the entity.

type · string · required

Must be "object".

title · string

User-friendly display name.

description · string

Description of what the entity represents.

properties · object · required

Object containing your field definitions. Each field has a type and optional validation rules.

Field types

Entities support various field types to define different kinds of data you can store: string, integer, number, boolean, array, and object. Each field inside properties requires a type. Based on the type, you can add validation options.

String fields

String fields support these options:

• minLength / maxLength: Control minimum and maximum character count.
• pattern: Regular expression for custom validation.
• format: Predefined formats. Supported values:
  • "date"
  • "date-time"
  • "time"
  • "email"
  • "uri"
  • "hostname"
  • "ipv4"
  • "ipv6"
  • "uuid"
• enum: Restrict to specific allowed values. Define as an array: ["value1", "value2", "value3"].
• default: Default value if none provided.

Integer fields

Integer fields support these options:

• minimum / maximum: Set inclusive lower/upper bounds.
• default: Default value if none provided.

Number fields

Number fields support these options:

• minimum / maximum: Set inclusive lower/upper bounds.
• default: Default value if none provided.

Boolean fields

Boolean fields support these options:

• default: Default value if none provided.

Array fields

Array fields support these options:

• items: Define the type/schema for array elements.
• default: Default array value if none provided.

Object fields

Object fields support these options:

• properties: Define the fields within the object.
• required: List of required property names.

Required fields

Specify which fields must be provided:

{
  "required": ["title", "email"]
}

Uniqueness

Base44 entities don’t support unique constraints. A property that isn’t part of the schema format, such as unique_fields, is stored with your schema and ignored.

To avoid duplicate records, check for an existing record in a backend function before you create a new one. A check like this narrows the window for duplicates but doesn’t close it. To make sure only one user succeeds, use the claim pattern in concurrent updates.

Concurrent updates

Base44 doesn’t lock records or run transactions across several records. When 2 users or processes change the same data at the same time, each write is applied on its own. This section covers which updates are atomic, how to claim a record safely, and what to expect from calls that write several records.

Claiming a record safely

To make sure only one user can claim an existing record, such as a task or a booking slot, call updateMany() with that single record’s id and the conditions that must still be true. The update is applied only if those conditions still match at the moment of the write, so when 2 users try at the same time, only one of them succeeds. Check updated in the response to see whether yours did.

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

The conditions are only checked again at the moment of the write when the query names a single record’s id as a plain value. Any other query, including several ids in $in or $or, finds the matching records first and then updates them, so a record that changed in between can still be updated.

Writing several records

bulkCreate(), bulkUpdate(), updateMany(), deleteMany() and upsert() aren’t transactions. Each record is written on its own, so if a call fails partway, the records already written stay written. Design these calls so they’re safe to run again, for example by filtering out records that were already updated.

Concurrent upsert() calls with the same key can create duplicate records.

Complete example

Here’s a complete entity schema:

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

Deploying entities

After defining your entity schema, deploy it to Base44 using entities push. Entities are also deployed automatically when you run the deploy command to deploy your entire project.

Once deployed, you can interact with your entities using the SDK’s entities module. The entity name in your schema must match exactly how you access it in the SDK, including capitalization. For example, if your schema has "name": "Task", you must access it as base44.entities.Task.list().

Deployed entity schemas can be viewed in the dashboard in the Data section.

See also

• User Schema: Special built-in entity for user authentication
• Security: Configure row-level security rules for entities
• Project Structure: How entity schemas fit into your project