Data Models

Data Model Overview

Data models in Fiberwise define the structure and behavior of your application's data. They provide:

Basic Model Definition

Define a data model in your app_manifest.yaml:

models:
  - name: Task
    model_slug: tasks
    description: User tasks with automatic isolation
    user_isolation: enforced  # ✅ Automatic user data protection
    fields:
      - name: Task ID
        field_column: task_id
        type: GENERATED_UUID
        required: true
        is_primary_key: true
        description: "Auto-generated unique identifier"
        
      - name: Title
        field_column: title
        type: string
        required: true
        max_length: 200
        
      - name: Description
        field_column: description
        type: text
        
      - name: Priority
        field_column: priority
        type: integer
        default: 1
        min_value: 1
        max_value: 5
        
      - name: Due Date
        field_column: due_date
        type: timestamp
        
      - name: Is Complete
        field_column: is_complete
        type: boolean
        default: false
        
      # System fields - automatically managed
      - name: User ID
        field_column: user_id
        type: integer
        required: true
        default: CURRENT_USER
        is_system_field: true
        description: "User ID for automatic isolation"
        
      - name: Created At
        field_column: created_at
        type: timestamp
        default: CURRENT_TIMESTAMP
        is_system_field: true

Field Types

Basic Types

Special Types

User Isolation

Every model should include user_isolation: enforced for automatic data protection:

models:
  - name: Customer
    model_slug: customers
    user_isolation: enforced  # ✅ Users can only see their own customers
    fields:
      - name: Customer Name
        field_column: name
        type: string
        required: true
        
      # user_id field automatically added for isolation
      - name: User ID
        field_column: user_id
        type: integer
        required: true
        default: CURRENT_USER
        is_system_field: true

System Fields

System fields are automatically managed by the platform and protected from user modification:

Required System Fields

# Always include these system fields
fields:
  # User isolation field
  - name: User ID
    field_column: user_id
    type: integer
    required: true
    default: CURRENT_USER
    is_system_field: true
    description: "User ID for automatic isolation"
    
  # Timestamp fields
  - name: Created At
    field_column: created_at
    type: timestamp
    default: CURRENT_TIMESTAMP
    is_system_field: true
    
  - name: Updated At
    field_column: updated_at
    type: timestamp
    default: CURRENT_TIMESTAMP
    is_system_field: true

System Field Properties

• is_system_field: true - Marks field as system-managed
• Automatic Population: Values set automatically by platform
• Read-Only: System fields cannot be manually modified
• Indexed: Automatically indexed for query performance

Field Validation

Common Validation Options

Validation Example

fields:
  - name: Email
    field_column: email
    type: string
    required: true
    max_length: 255
    pattern: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
    description: "Valid email address"
    
  - name: Age
    field_column: age
    type: integer
    min_value: 0
    max_value: 150
    description: "Age in years"
    
  - name: Status
    field_column: status
    type: string
    default: "active"
    enum: ["active", "inactive", "pending"]

Model Relationships

Foreign Key References

models:
  - name: Project
    model_slug: projects
    user_isolation: enforced
    fields:
      - name: Project ID
        field_column: project_id
        type: GENERATED_UUID
        required: true
        is_primary_key: true
        
      - name: Project Name
        field_column: name
        type: string
        required: true

  - name: Task
    model_slug: tasks
    user_isolation: enforced
    fields:
      - name: Task ID
        field_column: task_id
        type: GENERATED_UUID
        required: true
        is_primary_key: true
        
      - name: Task Name
        field_column: name
        type: string
        required: true
        
      # Foreign key relationship
      - name: Project
        field_column: project_id
        type: uuid
        required: true
        references: projects  # References the projects model
        description: "Associated project"

Reference Properties

• references: The model_slug of the referenced model
• User Isolation: References respect user isolation automatically
• Foreign Key Constraints: Database-level referential integrity
• Cascade Options: Configure delete behavior

Database Schema Generation

Fiberwise automatically generates database schemas from your model definitions:

Generated SQL Example

-- Auto-generated from model definition
CREATE TABLE app_tasks (
    task_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),  -- GENERATED_UUID
    title VARCHAR(200) NOT NULL,                         -- string with max_length
    description TEXT,                                    -- text field
    priority INTEGER DEFAULT 1 CHECK (priority >= 1 AND priority <= 5),
    due_date TIMESTAMP,                                  -- timestamp field
    is_complete BOOLEAN DEFAULT false,                   -- boolean with default
    user_id INTEGER NOT NULL REFERENCES users(id),      -- System field for isolation
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,     -- System timestamp
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP      -- System timestamp
);

-- Automatic indexes for performance
CREATE INDEX idx_app_tasks_user_id ON app_tasks(user_id);
CREATE INDEX idx_app_tasks_created_at ON app_tasks(created_at);

Schema Features

• Automatic Tables: Tables created based on model definitions
• Constraints: Type checking, length limits, and value ranges
• Indexes: Performance optimization for common queries
• Foreign Keys: Referential integrity between models
• User Isolation: Built-in user_id filtering

Advanced Model Features

Computed Fields

fields:
  - name: Full Name
    field_column: full_name
    type: string
    computed: true
    expression: "CONCAT(first_name, ' ', last_name)"
    description: "Computed from first and last name"

JSON Schema Fields

fields:
  - name: Metadata
    field_column: metadata
    type: json
    schema:
      type: object
      properties:
        category:
          type: string
          enum: ["urgent", "normal", "low"]
        tags:
          type: array
          items:
            type: string
      required: ["category"]

Encrypted Fields

fields:
  - name: Social Security Number
    field_column: ssn
    type: string
    encrypted: true
    description: "Encrypted sensitive data"

Best Practices

✅ Do

• Always use user_isolation: enforced for user-specific data
• Include system fields (user_id, created_at, updated_at)
• Use GENERATED_UUID for primary keys
• Add validation rules to ensure data quality
• Document field purposes with clear descriptions
• Use appropriate field types for data semantics

❌ Don't

• Don't skip user isolation on user-specific models
• Don't manually manage user_id - it's automatic
• Don't use overly long field names - keep them descriptive but concise
• Don't store sensitive data without encryption
• Don't create circular references between models

Naming Conventions

• Model Names: Singular, PascalCase (e.g., "Customer", "Order Item")
• Model Slugs: Plural, lowercase, hyphenated (e.g., "customers", "order-items")
• Field Names: Descriptive, Title Case (e.g., "Customer Name", "Due Date")
• Field Columns: Snake_case database columns (e.g., "customer_name", "due_date")

Schema Migrations

When you update your model definitions, Fiberwise handles schema migrations automatically:

Safe Migration Types

• Adding Fields: New optional fields are added safely
• Relaxing Constraints: Making required fields optional
• Increasing Limits: Expanding max_length or max_value
• Adding Indexes: Performance optimizations

Breaking Changes

• Removing Fields: Requires manual migration
• Changing Types: May require data conversion
• Adding Constraints: Must validate existing data
• Renaming Fields: Requires migration strategy