Entity Schema & Validation

Define entity schemas with validation rules in your tenant config. Validation runs both server-side and can be used client-side via the SDK.

Configuration

Add entities to your tenant config:

{
  "entities": {
    "definitions": {
      "User": {
        "name": "User",
        "description": "Application users",
        "tableName": "users",
        "fields": {
          "email": {
            "type": "text",
            "validation": { "required": true, "preset": "email" }
          },
          "name": {
            "type": "text",
            "validation": { "required": true, "min": 2, "max": 100 }
          },
          "age": {
            "type": "integer",
            "validation": { "min": 18, "max": 120 }
          },
          "status": {
            "type": "enum",
            "validation": { "enum": ["active", "inactive", "pending"] }
          }
        },
        "timestamps": true,
        "softDelete": true
      }
    },
    "validation": {
      "enabled": true,
      "strictMode": false,
      "sanitize": true
    }
  }
}

Field Types

Type	Description	Example
text	Variable-length string	Names, descriptions
varchar	Fixed-length string	Codes, slugs
integer	Whole numbers	Age, count
bigint	Large integers	IDs, timestamps
decimal	Floating point	Prices, percentages
boolean	True/false	Flags, toggles
timestamp	Date and time	Created at
date	Date only	Birth date
json	JSON object	Settings, metadata
jsonb	Binary JSON	Complex data
array	Array of values	Tags, categories
uuid	UUID string	Unique identifiers
enum	Enumerated values	Status, role

Validation Rules

Basic Rules

{
  "validation": {
    "required": true,
    "min": 3,
    "max": 100,
    "pattern": "^[a-z]+$",
    "message": "Custom error message"
  }
}

Rule	Type	Description
required	boolean	Field must have a value
min	number	Min length (strings) or value (numbers)
max	number	Max length (strings) or value (numbers)
pattern	string	Regex pattern to match
preset	string	Use a validation preset
enum	string[]	Allowed values list
message	string	Custom error message

Validation Presets

Use presets for common validation patterns:

{
  "email": { "type": "text", "validation": { "preset": "email" } },
  "website": { "type": "text", "validation": { "preset": "url" } },
  "phone": { "type": "text", "validation": { "preset": "phone-us" } }
}

Preset	Description	Pattern
email	Email address	user@example.com
url	HTTP/HTTPS URL	https://example.com
phone-us	US phone number	(555) 123-4567
phone-intl	International phone	+1 555 123 4567
uuid	UUID v1-5	550e8400-e29b-41d4-a716-446655440000
slug	URL slug	my-blog-post
username	Username (3-30 chars)	john_doe123
password	Min 8 characters	********
name	Person name	John O'Brien
currency	Currency amount	123.45
percentage	0-100 percentage	85.5
date	ISO date	2024-01-15
datetime	ISO datetime	2024-01-15T10:30:00Z
time	Time	14:30:00
ip	IPv4 or IPv6	192.168.1.1
ipv4	IPv4 only	192.168.1.1
ipv6	IPv6 only	2001:0db8::1
mac-address	MAC address	00:1A:2B:3C:4D:5E
credit-card	Card number	4111111111111111
postal-code-us	US ZIP code	12345 or 12345-6789
ssn	US SSN format	123-45-6789
hex-color	Hex color	#FF5733
json	Valid JSON string	{"key": "value"}

Enum Validation

{
  "status": {
    "type": "enum",
    "validation": {
      "required": true,
      "enum": ["draft", "published", "archived"]
    }
  }
}

Entity Options

{
  "name": "Product",
  "tableName": "products",
  "description": "Product catalog",
  "timestamps": true,
  "softDelete": true,
  "generateRoutes": {
    "create": true,
    "read": true,
    "update": true,
    "delete": true,
    "list": true
  },
  "permissions": {
    "create": ["admin", "editor"],
    "read": ["admin", "editor", "viewer"],
    "update": ["admin", "editor"],
    "delete": ["admin"]
  }
}

Option	Default	Description
tableName	snake_case of name	Database table/collection name
timestamps	true	Add created_at/updated_at
softDelete	false	Add deleted/deleted_at fields
generateRoutes	all true	Auto-generate CRUD routes
permissions	none	Role-based access per operation

SDK Usage

Get Schema

const bf = await createBackflow({ clientKey: 'your-key' });

// Get all schemas
const schemas = await bf.entities.getSchema();

// Get schema for specific collection
const userSchema = await bf.entities.getCollectionSchema('users');

console.log(userSchema);
// {
//   collection: 'users',
//   fields: [
//     { name: 'id', source: 'builtin' },
//     { name: 'email', source: 'entity', type: 'text', required: true, preset: 'email' },
//     { name: 'age', source: 'entity', type: 'integer', min: 18, max: 120 }
//   ]
// }

Client-Side Validation

// Validate data before sending
const result = await bf.entities.validate('users', {
  email: 'invalid-email',
  age: 15
});

if (!result.valid) {
  console.log(result.errors);
  // [
  //   { field: 'email', message: 'email must be a valid email' },
  //   { field: 'age', message: 'age must be at least 18' }
  // ]
}

Create/Update with Validation

// Validates before sending to server
const { data, errors } = await bf.entities.createValidated('users', {
  email: 'user@example.com',
  name: 'John Doe',
  age: 25
});

if (errors) {
  // Handle validation errors
  console.error(errors);
} else {
  // Success
  console.log(data);
}

// Same for updates
const updateResult = await bf.entities.updateValidated('users', userId, {
  name: 'Jane Doe'
});

Admin UI

Use the Schema Builder in the admin dashboard to:

1. Create/edit entities visually
2. Add fields with type selection
3. Configure validation rules via dropdowns
4. Set presets without writing regex
5. Preview and copy JSON config

Navigate to API & Data > Schema Builder in the admin panel.

API Response

The /admin/schema endpoint returns field validation info:

{
  "data": [
    {
      "collection": "users",
      "fields": [
        { "name": "id", "source": "builtin" },
        { "name": "created_at", "source": "builtin" },
        { "name": "email", "source": "entity", "type": "text", "required": true, "preset": "email" },
        { "name": "age", "source": "entity", "type": "integer", "min": 18, "max": 120 },
        { "name": "status", "source": "entity", "type": "enum", "enum": ["active", "inactive"] }
      ]
    }
  ]
}

Field sources:

• builtin: System fields (id, created_at, updated_at, deleted, deleted_at)
• route: Inferred from route definitions
• entity: Defined in entity schema with validation

Examples

User Entity

{
  "User": {
    "name": "User",
    "fields": {
      "email": { "type": "text", "validation": { "required": true, "preset": "email" } },
      "password": { "type": "text", "validation": { "required": true, "preset": "password" } },
      "username": { "type": "text", "validation": { "required": true, "preset": "username" } },
      "role": { "type": "enum", "validation": { "enum": ["user", "admin", "moderator"] } },
      "profile": { "type": "jsonb" }
    },
    "timestamps": true
  }
}

Product Entity

{
  "Product": {
    "name": "Product",
    "tableName": "products",
    "fields": {
      "name": { "type": "text", "validation": { "required": true, "min": 3, "max": 200 } },
      "slug": { "type": "text", "validation": { "required": true, "preset": "slug" }, "unique": true },
      "price": { "type": "decimal", "validation": { "required": true, "min": 0 } },
      "status": { "type": "enum", "validation": { "enum": ["draft", "published", "archived"] } },
      "tags": { "type": "array" },
      "metadata": { "type": "jsonb" }
    },
    "timestamps": true,
    "softDelete": true
  }
}

Order Entity

{
  "Order": {
    "name": "Order",
    "fields": {
      "order_number": { "type": "text", "validation": { "required": true }, "unique": true },
      "customer_email": { "type": "text", "validation": { "required": true, "preset": "email" } },
      "total": { "type": "decimal", "validation": { "required": true, "min": 0 } },
      "status": { "type": "enum", "validation": { "required": true, "enum": ["pending", "paid", "shipped", "delivered", "cancelled"] } },
      "shipping_address": { "type": "jsonb", "validation": { "required": true } }
    },
    "timestamps": true,
    "softDelete": true,
    "permissions": {
      "create": ["admin", "system"],
      "read": ["admin", "user"],
      "update": ["admin"],
      "delete": ["admin"]
    }
  }
}