Schema Design

A FLXBL schema defines your data model with entities (like tables) and relationships (graph edges connecting entities).

Visual Schema Editor

The easiest way to design your schema is using the visual Schema Editor in your FLXBL dashboard. Create entities, define fields with dropdown type selectors, and draw relationships by dragging between entity nodes.

FLXBL Entity Editor Panel showing field types and configuration
Entity Editor Panel with fields, types, and required toggles

The Schema Editor automatically handles versioning and shows a breaking changes dialog when you modify existing fields.

Entities

An entity represents a type of data in your application. Each entity has a name and a list of fields with types. 

{
  "name": "Product",
  "description": "Products available in the store",
  "fields": [
    { 
      "name": "name", 
      "type": "STRING", 
      "required": true,
      "description": "Product display name"
    },
    { 
      "name": "description", 
      "type": "TEXT", 
      "required": false,
      "description": "Detailed product description"
    },
    { 
      "name": "price", 
      "type": "FLOAT", 
      "required": true 
    },
    { 
      "name": "quantity", 
      "type": "NUMBER", 
      "required": true 
    },
    { 
      "name": "isActive", 
      "type": "BOOLEAN", 
      "required": false 
    },
    { 
      "name": "publishedAt", 
      "type": "DATETIME", 
      "required": false 
    },
    { 
      "name": "metadata", 
      "type": "JSON", 
      "required": false 
    },
    { 
      "name": "status", 
      "type": "ENUM", 
      "required": true,
      "enumValues": ["draft", "published", "archived"]
    },
    { 
      "name": "tags", 
      "type": "STRING_ARRAY", 
      "required": false 
    }
  ]
}

Field Types

FLXBL supports the following field types:

Type Description Example Values
STRING Short text (up to 255 chars) "Hello World"
TEXT Long text (unlimited) Article body, descriptions
NUMBER Integer 42, -10, 0
FLOAT Decimal number 3.14, 99.99
BOOLEAN True/false true, false
DATETIME ISO 8601 timestamp "2025-01-15T10:30:00Z"
JSON Arbitrary JSON object {"key": "value"}
ENUM Predefined values "draft", "published"
STRING_ARRAY Array of strings ["tag1", "tag2"]
NUMBER_ARRAY Array of integers [1, 2, 3]
FLOAT_ARRAY Array of decimals [1.5, 2.5, 3.5]
BOOLEAN_ARRAY Array of booleans [true, false, true]

Field Options

  • name (required) - Field identifier, must be unique within entity
  • type (required) - One of the supported field types
  • required (required) - Whether the field must have a value
  • description (optional) - Human-readable description
  • enumValues (required for ENUM) - Array of allowed values

Relationships

Relationships define how entities connect to each other. FLXBL stores these as graph edges in Neo4j, enabling powerful traversal queries. 

{
  "relationships": [
    {
      "name": "BELONGS_TO",
      "sourceEntityName": "Product",
      "targetEntityName": "Category",
      "cardinality": "MANY_TO_ONE",
      "description": "Products belong to one category"
    },
    {
      "name": "PURCHASED_BY",
      "sourceEntityName": "Product",
      "targetEntityName": "Customer",
      "cardinality": "MANY_TO_MANY",
      "fields": [
        { "name": "quantity", "type": "NUMBER", "required": true },
        { "name": "purchasedAt", "type": "DATETIME", "required": true },
        { "name": "unitPrice", "type": "FLOAT", "required": true }
      ]
    },
    {
      "name": "REVIEWED_BY",
      "sourceEntityName": "Product",
      "targetEntityName": "Customer",
      "cardinality": "ONE_TO_MANY",
      "fields": [
        { "name": "rating", "type": "NUMBER", "required": true },
        { "name": "comment", "type": "TEXT", "required": false }
      ]
    }
  ]
}

Cardinality Types

Cardinality Description Example
ONE_TO_ONE Each source links to exactly one target User → Profile
ONE_TO_MANY Each source links to multiple targets Author → Posts
MANY_TO_ONE Multiple sources link to one target Products → Category
MANY_TO_MANY Multiple sources link to multiple targets Products ↔ Tags

Relationship Properties

Relationships can have their own fields (properties on the edge). This is useful for storing metadata about the connection:

  • PURCHASED_BY: quantity, purchasedAt, unitPrice
  • REVIEWED_BY: rating, comment, createdAt
  • FOLLOWS: followedAt, notificationsEnabled

Complete Schema Example

Here's a complete schema for an e-commerce application:

{
  "entities": [
    {
      "name": "Product",
      "fields": [
        { "name": "name", "type": "STRING", "required": true },
        { "name": "price", "type": "FLOAT", "required": true },
        { "name": "tags", "type": "STRING_ARRAY", "required": false }
      ]
    },
    {
      "name": "Category",
      "fields": [
        { "name": "name", "type": "STRING", "required": true },
        { "name": "slug", "type": "STRING", "required": true }
      ]
    },
    {
      "name": "Customer",
      "fields": [
        { "name": "email", "type": "STRING", "required": true },
        { "name": "name", "type": "STRING", "required": true }
      ]
    }
  ],
  "relationships": [
    {
      "name": "BELONGS_TO",
      "sourceEntityName": "Product",
      "targetEntityName": "Category",
      "cardinality": "MANY_TO_ONE"
    },
    {
      "name": "PURCHASED_BY",
      "sourceEntityName": "Product",
      "targetEntityName": "Customer",
      "cardinality": "MANY_TO_MANY",
      "fields": [
        { "name": "quantity", "type": "NUMBER", "required": true }
      ]
    }
  ],
  "description": "E-commerce schema with products, categories, and customers"
}

Schema Validation

Before publishing, you should validate your schema to catch errors: 

// Ask your AI assistant:
"Validate my schema before publishing it"

// Or use the MCP tool directly:
validate_schema({
  entities: [...],
  relationships: [...]
})

The validator checks for:

  • Reserved entity names (id, createdAt, updatedAt)
  • Invalid field types
  • Missing required properties
  • Duplicate entity or field names
  • Invalid relationship references
  • Breaking changes from previous versions

Best Practices

  • Use descriptive names: Entity and field names should be self-documenting
  • Add descriptions: Help future developers understand your schema
  • Start simple: Begin with core entities and add complexity later
  • Use relationships: Graph relationships are more flexible than embedding
  • Consider queries: Design your schema based on how you'll query data

Next Steps