Skip to content

field-types.md

Latest commit

 

History

History
348 lines (287 loc) · 8.54 KB

field-types.md

File metadata and controls

348 lines (287 loc) · 8.54 KB
Raw

Field Types Reference

Quick reference for choosing the right field type from 48 available options.

Text & Content

Type When to Use Config
text Single-line strings (names, codes, titles) maxLength, minLength, defaultValue
textarea Multi-line plain text (notes, descriptions) maxLength, rows
email Email addresses — built-in format validation required, unique
url Web URLs — built-in format validation required
phone Phone numbers format (custom regex)
password Masked / hashed input minLength, hashAlgorithm
markdown Markdown-formatted content maxLength
html Raw HTML content maxLength, sanitize
richtext WYSIWYG rich text editor maxLength

Numbers

Type When to Use Config
number Generic numeric value min, max, precision, step
currency Monetary amounts currencyConfig (precision, currencyMode, defaultCurrency)
percent Percentage values (0-100) min, max, precision

Date & Time

Type When to Use Config
date Date only (no time component) defaultValue, min, max
datetime Full date + time defaultValue, timezone
time Time only (no date component) defaultValue, format

Logic

Type When to Use Config
boolean Standard checkbox defaultValue
toggle Toggle switch (distinct UI from checkbox) defaultValue

Selection

Type When to Use Config
select Single-choice dropdown options (value, label, color, default)
multiselect Tag-style multi-choice options, max
radio Radio button group (fewer choices, always visible) options
checkboxes Checkbox group options

Critical: Every option must have lowercase value and human-readable label.

options: [
  { label: 'In Progress', value: 'in_progress', color: '#3498db' },
  { label: 'Done', value: 'done', default: true },
]

Relational

Type When to Use Key Config
lookup Reference another object (independent) reference, referenceFilters, multiple
master_detail Parent–child with lifecycle control reference, deleteBehavior (cascade/restrict/set_null)
tree Hierarchical self-reference reference

Set multiple: true on lookup for many-to-many via junction.

Media

Type When to Use Config
image Image files (PNG, JPG, GIF, WebP) fileAttachmentConfig (maxSize, allowedTypes, storage)
file Generic file attachments fileAttachmentConfig, allowedExtensions
avatar User/profile picture fileAttachmentConfig, cropAspectRatio
video Video files fileAttachmentConfig, maxDuration
audio Audio files fileAttachmentConfig, maxDuration

All use fileAttachmentConfig for size limits, allowed types, virus scanning, and storage provider.

Calculated

Type When to Use Config
formula Computed from an expression referencing other fields expression, resultType
summary Roll-up aggregation from child records summaryType (count/sum/min/max/avg), summaryField, reference
autonumber Auto-incrementing display format format (e.g., "CASE-{0000}")

Enhanced Types

Type When to Use Config
location Geographic coordinates (lat/lng) defaultZoom, enableSearch
address Structured address (street, city, country) countryFilter, autocomplete
code Syntax-highlighted code editor language, theme
json JSON data schema (JSON Schema for validation)
color Color picker format (hex/rgb/hsl), alpha
rating Star/heart rating max (default 5), icon
slider Numeric slider min, max, step
signature Digital signature pad signatureConfig
qrcode QR code generator qrConfig
progress Progress bar min, max, showPercentage
tags Free-form tag input max, delimiter, caseSensitive
vector AI/ML embeddings (semantic search, RAG) vectorConfig (dimensions, distanceMetric, indexType)

Field Type Decision Tree

What kind of data?
│
├── Text?
│   ├── Single line → text
│   ├── Multiple lines → textarea
│   ├── Formatted → richtext / markdown / html
│   ├── Email → email
│   ├── URL → url
│   ├── Phone → phone
│   └── Code → code
│
├── Number?
│   ├── Money → currency
│   ├── Percentage → percent
│   └── Generic → number
│
├── Date/Time?
│   ├── Date only → date
│   ├── Time only → time
│   └── Date + Time → datetime
│
├── True/False?
│   ├── Checkbox → boolean
│   └── Switch → toggle
│
├── Choose from list?
│   ├── Single choice, dropdown → select
│   ├── Single choice, always visible → radio
│   ├── Multiple choice, tags → multiselect
│   └── Multiple choice, checkboxes → checkboxes
│
├── Reference another object?
│   ├── Independent → lookup
│   ├── Owned child → master_detail
│   └── Hierarchy → tree
│
├── File/Media?
│   ├── Image → image
│   ├── Video → video
│   ├── Audio → audio
│   ├── User photo → avatar
│   └── Generic file → file
│
├── Calculated?
│   ├── Formula → formula
│   ├── Roll-up → summary
│   └── Auto-number → autonumber
│
└── Special?
    ├── Location → location
    ├── Address → address
    ├── Color → color
    ├── Rating → rating
    ├── Signature → signature
    ├── QR code → qrcode
    ├── Progress → progress
    ├── Tags → tags
    ├── JSON data → json
    └── AI embeddings → vector

Common Field Configurations

Text with Max Length

{
  type: 'text',
  maxLength: 255,
  required: true,
}

Email with Uniqueness

{
  type: 'email',
  required: true,
  unique: true,
}

Currency with Precision

{
  type: 'currency',
  currencyConfig: {
    precision: 2,
    currencyMode: 'multi',  // or 'single'
    defaultCurrency: 'USD',
  },
}

Select with Default

{
  type: 'select',
  required: true,
  options: [
    { label: 'Low', value: 'low' },
    { label: 'Medium', value: 'medium', default: true },
    { label: 'High', value: 'high', color: '#e74c3c' },
  ],
}

Lookup (One-to-Many)

{
  type: 'lookup',
  reference: 'account',
  required: true,
  referenceFilters: {
    status: 'active',
  },
}

Lookup (Many-to-Many)

{
  type: 'lookup',
  reference: 'tag',
  multiple: true,
  max: 10,
}

Master-Detail with Cascade

{
  type: 'master_detail',
  reference: 'invoice',
  deleteBehavior: 'cascade',
  required: true,
}

Formula

{
  type: 'formula',
  expression: 'amount * tax_rate',
  resultType: 'currency',
}

Summary (Roll-up)

{
  type: 'summary',
  reference: 'invoice_line_item',
  summaryType: 'sum',
  summaryField: 'amount',
}

Autonumber

{
  type: 'autonumber',
  format: 'CASE-{0000}',
}

Vector (AI Embeddings)

{
  type: 'vector',
  vectorConfig: {
    dimensions: 1536,  // OpenAI ada-002
    distanceMetric: 'cosine',
    indexType: 'hnsw',
  },
}

Incorrect vs Correct

❌ Incorrect — Wrong Type for Email

{
  type: 'text',  // ❌ No built-in email validation
  maxLength: 255,
}

✅ Correct — Use email Type

{
  type: 'email',  // ✅ Built-in validation + UI affordances
}

❌ Incorrect — Uppercase Option Value

options: [
  { label: 'Done', value: 'Done' },  // ❌ Uppercase
]

✅ Correct — Lowercase Option Value

options: [
  { label: 'Done', value: 'done' },  // ✅ Lowercase
]

❌ Incorrect — Missing Reference

{
  type: 'lookup',  // ❌ No reference specified
}

✅ Correct — Specify Reference

{
  type: 'lookup',
  reference: 'account',  // ✅ Target object specified
}