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

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