Skip to main content

Fields

Fields are database columns with additional metadata and configuration in TrackVision AI. They represent how data is stored, displayed, and managed within collections, defining the individual data elements that structure your business information.

Overview​

A field in TrackVision AI combines database schema definition with user interface configuration, providing comprehensive control over data storage, validation, presentation, and user interaction. Each field includes:

  • Database column specifications and constraints
  • User interface behavior and appearance
  • Validation rules and data integrity checks
  • Display formatting and presentation options
  • Relationship definitions to other collections

Field Categories​

Text Types​

String​

Short text data with configurable length limits and formatting options.

Use cases: Names, titles, codes, short descriptions Database type: VARCHAR Properties:

  • max_length: Maximum character count (default: 255)
  • trim: Automatically remove whitespace from input
  • mask: Input formatting pattern for consistent data entry
  • slug: Auto-generate URL-friendly slugs from input

Text​

Long-form text content with rich formatting capabilities.

Use cases: Descriptions, articles, comments, documentation Database type: TEXT Properties:

  • toolbar: Rich text editor toolbar configuration
  • folder: File upload destination for embedded media
  • sanitize: HTML content sanitization rules

UUID​

Universally unique identifiers, automatically generated or manually entered.

Use cases: Primary keys, external references, secure identifiers Database type: UUID Properties:

  • readonly: Prevent manual editing after creation
  • hidden: Hide from user interface

Hash​

Encrypted storage for sensitive data like passwords.

Use cases: Passwords, API keys, secure tokens Database type: VARCHAR Properties:

  • masked: Hide value in interface (show asterisks)
  • hash: Hashing algorithm (bcrypt, argon2, sha256)

Alias​

Virtual fields that don't map to database columns but provide interface functionality.

Use cases: Computed values, UI helpers, display-only information Database type: None (virtual) Properties:

  • interface: Custom interface for user interaction
  • display: Custom display formatting

Numeric Types​

Integer​

Whole numbers with range validation and display formatting.

Use cases: Counts, IDs, quantities, rankings Database type: INTEGER Properties:

  • min_value: Minimum allowed value
  • max_value: Maximum allowed value
  • step: Increment/decrement step size

Big Integer​

Large whole numbers for high-volume scenarios.

Use cases: Large datasets, high-precision counts, timestamps Database type: BIGINT Properties:

  • min_value: Minimum allowed value
  • max_value: Maximum allowed value
  • step: Increment/decrement step size

Float​

Decimal numbers with precision control.

Use cases: Measurements, percentages, scientific data Database type: FLOAT Properties:

  • min_value: Minimum allowed value
  • max_value: Maximum allowed value
  • step: Increment/decrement step size
  • precision: Number of decimal places

Decimal​

High-precision decimal numbers for financial calculations.

Use cases: Currency, financial calculations, precise measurements Database type: DECIMAL Properties:

  • precision: Total number of digits
  • scale: Number of digits after decimal point
  • min_value: Minimum allowed value
  • max_value: Maximum allowed value

Boolean Type​

Boolean​

True/false values with customizable labels and icons.

Use cases: Flags, settings, status indicators, yes/no questions Database type: BOOLEAN Properties:

  • label: Custom labels for true/false states
  • icon_on: Icon displayed when true
  • icon_off: Icon displayed when false

Date and Time Types​

DateTime​

Date and time stamps with timezone support.

Use cases: Created/updated timestamps, event dates, scheduling Database type: TIMESTAMP Properties:

  • include_seconds: Show seconds in time picker
  • 24hour: Use 24-hour time format
  • min: Minimum allowed date/time
  • max: Maximum allowed date/time

Date​

Date-only values without time information.

Use cases: Birth dates, deadlines, event dates Database type: DATE Properties:

  • min: Minimum allowed date
  • max: Maximum allowed date

Time​

Time-only values without date information.

Use cases: Business hours, time slots, durations Database type: TIME Properties:

  • include_seconds: Include seconds in time selection
  • 24hour: Use 24-hour format

Timestamp​

Unix timestamp values for precise time tracking.

Use cases: System timestamps, API integrations, precise timing Database type: INTEGER Properties:

  • readonly: Prevent manual editing
  • auto_update: Automatically update on record changes

Binary Types​

File​

File uploads with type restrictions and storage configuration.

Use cases: Documents, attachments, media files Database type: UUID (reference to files table) Properties:

  • folder: Upload destination folder
  • accept: Allowed file types (MIME types)
  • max_size: Maximum file size in bytes

Image​

Image files with transformation and optimization options.

Use cases: Photos, logos, graphics, thumbnails Database type: UUID (reference to files table) Properties:

  • folder: Upload destination folder
  • crop: Enable image cropping tools
  • dimension_constraints: Width/height limits
  • quality: JPEG compression quality

Structured Types​

JSON​

Structured data objects with schema validation.

Use cases: Configuration data, API responses, complex structures Database type: JSON Properties:

  • template: JSON schema template
  • validation: JSON schema for validation

CSV​

Comma-separated values for simple lists.

Use cases: Tags, simple lists, multi-select options Database type: TEXT Properties:

  • delimiter: Character used to separate values
  • trim: Remove whitespace from values

Geospatial Types​

Geometry​

Spatial data and coordinates for mapping applications.

Use cases: Locations, boundaries, geographic data Database type: GEOMETRY (requires spatial extension) Properties:

  • geometry_types: Allowed types (Point, LineString, Polygon)
  • max_features: Maximum number of features

Field Configuration​

Schema Configuration​

Database Settings​

  • Field Key: Unique identifier within collection (immutable)
  • Type: Database column type (immutable after creation)
  • Length: Maximum data length for applicable types
  • Default Value: Value assigned to new records
  • Allow Null: Whether field can contain null values

Constraints​

  • Primary Key: Mark field as primary key
  • Unique: Enforce uniqueness across collection
  • Not Null: Require value for all records
  • Auto Increment: Automatic number generation (integers only)

Field Configuration​

Basic Properties​

  • Display Name: Human-readable field label
  • Note: Description or help text for users
  • Translation Key: Internationalization identifier
  • Required: Field must have value when creating items
  • Readonly: Prevent editing after initial creation
  • Hidden: Hide field from user interface

Advanced Properties​

  • Width: Field width in forms (full, half, quarter)
  • Sort: Custom ordering within field groups
  • Group: Logical grouping of related fields
  • Validation: Custom validation rules and messages

Interface Configuration​

Interfaces define how users create, edit, and view field data:

Input Interfaces​

  • Input: Simple text input
  • Textarea: Multi-line text input
  • Wysiwyg: Rich text editor
  • Code: Syntax-highlighted code editor
  • Slider: Numeric range input
  • Toggle: Boolean switch
  • Dropdown: Select from predefined options
  • Checkboxes: Multiple selection options
  • Radio Buttons: Single selection from options

File Interfaces​

  • File: File upload and management
  • Files: Multiple file upload
  • Image: Image upload with preview
  • Gallery: Multiple image management

Relational Interfaces​

  • Many-to-One: Select related record
  • One-to-Many: Manage child records
  • Many-to-Many: Select multiple related records
  • Translations: Manage multi-language content

Display Configuration​

Display options control how field values are presented:

Text Displays​

  • Raw: Show value as-is
  • Formatted Text: Apply text formatting
  • Markdown: Render markdown content
  • Code: Syntax highlighting for code

Numeric Displays​

  • Formatted Number: Number formatting with locale
  • Currency: Currency formatting
  • Percentage: Percentage display
  • Filesize: Byte size formatting

Date Displays​

  • Datetime: Full date and time formatting
  • Date: Date-only formatting
  • Time: Time-only formatting
  • Relative Time: Time ago/from now

Media Displays​

  • Image: Image preview and lightbox
  • File: File download link
  • Video: Video player embed

Validation Configuration​

Built-in Validators​

  • Required: Field must have value
  • Unique: Value must be unique in collection
  • Email: Valid email address format
  • URL: Valid URL format
  • Length: Minimum/maximum character count
  • Range: Numeric min/max values
  • Pattern: Regular expression matching

Custom Validation​

Define custom validation logic:

// Custom email domain validation
function validateCompanyEmail(value) {
  if (!value) return true; // Allow empty if not required
  const allowedDomains = ['company.com', 'subsidiary.com'];
  const domain = value.split('@')[1];
  return allowedDomains.includes(domain) || 'Must use company email address';
}

Validation Messages​

  • Custom Messages: Override default validation messages
  • Internationalization: Translated validation messages
  • Dynamic Messages: Context-aware validation feedback

Conditions Configuration​

Dynamic field behavior based on other field values:

Visibility Conditions​

Show/hide fields based on other field values:

{
  "name": "shipping_address",
  "rule": {
    "_and": [
      {
        "shipping_required": {
          "_eq": true
        }
      }
    ]
  }
}

Required Conditions​

Make fields required based on conditions:

{
  "name": "billing_address", 
  "rule": {
    "_and": [
      {
        "payment_method": {
          "_eq": "invoice"
        }
      }
    ]
  }
}

Value Conditions​

Set field values based on other fields:

{
  "name": "full_name",
  "rule": {
    "_and": [
      {
        "first_name": {
          "_nnull": true
        }
      },
      {
        "last_name": {
          "_nnull": true
        }
      }
    ]
  }
}

Field Management​

Creating Fields​

Fields can be created through multiple methods:

  1. Platform Admin Interface: Visual field builder
  2. REST API: Programmatic field creation
  3. GraphQL Schema: Schema-first development
  4. Database Migrations: Version-controlled changes
  5. Schema Import: Import from existing database

Field Updates​

Safe Updates​

  • Adding validation rules (if data complies)
  • Updating display properties
  • Modifying interface configuration
  • Adding help text and notes

Breaking Changes​

  • Changing field type
  • Renaming field key
  • Adding non-nullable constraints
  • Removing fields with data

Field Deletion​

Soft Deletion​

  • Hide field from interface
  • Preserve data in database
  • Allow restoration if needed

Hard Deletion​

  • Remove field from database
  • Permanently delete all data
  • Cannot be undone

System Fields​

TrackVision AI automatically creates system fields for accountability:

Standard System Fields​

  • id: Primary key (UUID or auto-increment)
  • status: Publication status
  • created_at: Creation timestamp
  • updated_at: Last modification timestamp
  • created_by: User who created the record
  • updated_by: User who last modified the record

Archive Fields​

  • archived: Soft deletion flag
  • archived_at: Archive timestamp
  • archived_by: User who archived the record

Performance Considerations​

Database Optimization​

Indexing Strategy​

  • Primary Keys: Automatically indexed
  • Foreign Keys: Automatically indexed
  • Unique Fields: Automatically indexed
  • Frequently Queried: Add manual indexes
  • Sort Fields: Index for performance
  • Filter Fields: Index common filter targets

Data Type Selection​

  • Storage Efficiency: Choose minimal required type
  • Query Performance: Consider index-friendly types
  • Application Needs: Balance storage vs. functionality

Interface Performance​

Field Loading​

  • Lazy Loading: Load fields as needed
  • Conditional Loading: Load based on user permissions
  • Batch Loading: Group field requests

User Experience​

  • Progressive Disclosure: Show relevant fields first
  • Field Grouping: Organize related fields
  • Smart Defaults: Reduce user input requirements

Best Practices​

Field Design​

Naming Conventions​

  1. Descriptive Names: Use clear, meaningful field names
  2. Consistent Patterns: Follow established naming conventions
  3. Snake Case: Use underscore_separated_names
  4. Avoid Abbreviations: Use full words when possible
  5. Database Reserved Words: Avoid SQL keywords

Data Types​

  1. Appropriate Selection: Choose most specific type
  2. Future-Proofing: Consider data evolution needs
  3. Validation Rules: Implement comprehensive validation
  4. Default Values: Provide sensible defaults
  5. Nullable Strategy: Decide null handling approach

User Experience​

Interface Design​

  1. Logical Grouping: Organize related fields together
  2. Progressive Disclosure: Show complex fields conditionally
  3. Help Text: Provide clear field descriptions
  4. Input Validation: Real-time feedback for users
  5. Accessibility: Support screen readers and keyboard navigation

Performance Optimization​

  1. Field Selection: Only load needed fields
  2. Conditional Loading: Load based on user context
  3. Caching Strategy: Cache frequently accessed data
  4. Pagination: Handle large datasets efficiently
  5. Batch Operations: Group related field operations

Data Management​

Validation Strategy​

  1. Client-Side: Immediate user feedback
  2. Server-Side: Authoritative validation
  3. Database Level: Final data integrity check
  4. Custom Rules: Business logic validation
  5. Error Handling: Graceful validation failure

Security Considerations​

  1. Input Sanitization: Clean user input
  2. Output Encoding: Prevent XSS attacks
  3. Permission Checks: Field-level access control
  4. Audit Logging: Track field value changes
  5. Sensitive Data: Proper handling of confidential information