Skip to content

field-type-decision-tree.mdx

Latest commit

 

History

History
257 lines (212 loc) · 10.1 KB

field-type-decision-tree.mdx

File metadata and controls

257 lines (212 loc) · 10.1 KB
Raw
title Field Type Decision Tree
description Interactive guide for choosing the right ObjectStack field type — decision flowchart, quick-reference table, and use case mapping

Field Type Decision Tree

Not sure which field type to use? Follow this decision tree to find the right type for your data, then check the quick-reference table for details.

**Full Details:** Once you've identified the right type, see the [Field Type Gallery](/docs/data-modeling/field-types) for complete configuration properties.

Decision Flowchart

flowchart TD
    START([What kind of data?]) --> TEXT{Text?}
    START --> NUM{Number?}
    START --> DATE{Date / Time?}
    START --> CHOICE{Choice / Selection?}
    START --> REL{Relationship?}
    START --> FILE{File / Media?}
    START --> COMP{Computed?}
    START --> STRUCT{Structured Data?}
    START --> AI{AI / ML?}

    %% Text branch
    TEXT -->|Short text| T1[text]
    TEXT -->|Long text| T2[textarea]
    TEXT -->|Rich formatting| T3[richtext]
    TEXT -->|Markdown content| T4[markdown]
    TEXT -->|Email address| T5[email]
    TEXT -->|Website URL| T6[url]
    TEXT -->|Phone number| T7[phone]
    TEXT -->|Secret value| T8[password]

    %% Number branch
    NUM -->|Any number| N1[number]
    NUM -->|Money amount| N3[currency]
    NUM -->|Percentage| N4[percent]
    NUM -->|Star rating| N5[rating]
    NUM -->|Slider input| N6[slider]

    %% Date branch
    DATE -->|Date only| D1[date]
    DATE -->|Date + time| D2[datetime]
    DATE -->|Time only| D3[time]

    %% Choice branch
    CHOICE -->|Single choice, dropdown| C1[select]
    CHOICE -->|Multiple choices| C2[multiselect]
    CHOICE -->|Single choice, visible| C3[radio]
    CHOICE -->|Multiple, visible| C4[checkboxes]
    CHOICE -->|On/off switch| C5[toggle]
    CHOICE -->|True/false| C6[boolean]

    %% Relationship branch
    REL -->|Reference another object| R1[lookup]
    REL -->|Parent-child cascade| R2[master_detail]
    REL -->|Self-referencing hierarchy| R3[tree]

    %% File branch
    FILE -->|Any file| F1[file]
    FILE -->|Image with preview| F2[image]
    FILE -->|User profile picture| F3[avatar]

    %% Computed branch
    COMP -->|Calculated value| K1[formula]
    COMP -->|Aggregate children| K2[summary]
    COMP -->|Auto-incrementing ID| K3[autonumber]

    %% Structured branch
    STRUCT -->|Postal address| S1[address]
    STRUCT -->|GPS coordinates| S2[location]
    STRUCT -->|Color picker| S3[color]
    STRUCT -->|Arbitrary JSON| S4[json]
    STRUCT -->|Sensitive secret value| S5[secret]

    %% AI branch
    AI -->|Vector embedding for semantic search| A1[vector]

    style START fill:#4f46e5,color:#fff
    style T1 fill:#059669,color:#fff
    style T2 fill:#059669,color:#fff
    style T3 fill:#059669,color:#fff
    style T4 fill:#059669,color:#fff
    style T5 fill:#059669,color:#fff
    style T6 fill:#059669,color:#fff
    style T7 fill:#059669,color:#fff
    style T8 fill:#059669,color:#fff
    style N1 fill:#d97706,color:#fff
    style N3 fill:#d97706,color:#fff
    style N4 fill:#d97706,color:#fff
    style N5 fill:#d97706,color:#fff
    style N6 fill:#d97706,color:#fff
    style D1 fill:#7c3aed,color:#fff
    style D2 fill:#7c3aed,color:#fff
    style D3 fill:#7c3aed,color:#fff
    style C1 fill:#dc2626,color:#fff
    style C2 fill:#dc2626,color:#fff
    style C3 fill:#dc2626,color:#fff
    style C4 fill:#dc2626,color:#fff
    style C5 fill:#dc2626,color:#fff
    style C6 fill:#dc2626,color:#fff
    style R1 fill:#0284c7,color:#fff
    style R2 fill:#0284c7,color:#fff
    style R3 fill:#0284c7,color:#fff
    style F1 fill:#be185d,color:#fff
    style F2 fill:#be185d,color:#fff
    style F3 fill:#be185d,color:#fff
    style K1 fill:#78716c,color:#fff
    style K2 fill:#78716c,color:#fff
    style K3 fill:#78716c,color:#fff
    style S1 fill:#0d9488,color:#fff
    style S2 fill:#0d9488,color:#fff
    style S3 fill:#0d9488,color:#fff
    style S4 fill:#0d9488,color:#fff
    style S5 fill:#0d9488,color:#fff
    style A1 fill:#6d28d9,color:#fff
Loading

Quick-Reference Table

Text Types

Type Use When Example
text Short single-line input (names, titles) first_name, title
textarea Multi-line content without formatting description, notes
richtext Formatted content with HTML/WYSIWYG article_body, bio
markdown Developer-friendly formatted content readme, documentation
email Email address with validation email, contact_email
url Web URL with validation website, linkedin_url
phone Phone number phone, mobile
password One-way hashed credential (owned by auth subsystem) user_password
secret Reversible encrypted-at-rest value, masked on read api_key, db_password

Number Types

Type Use When Example
number Any numeric value (set precision/scale for decimals) price, weight, quantity
currency Money amounts with currency code amount, total_price
percent Percentage values, stored as fractions 0–1 (0.85 = 85%) completion, discount
rating Star ratings (typically 1–5) satisfaction, difficulty
slider Numeric value via slider UI volume, priority_level

Date & Time Types

Type Use When Example
date Calendar date without time birth_date, due_date
datetime Full timestamp with timezone created_at, meeting_start
time Time of day without date start_time, reminder_time

Choice Types

Type Use When Example
select Pick one from a dropdown list status, category
multiselect Pick multiple from a dropdown tags, skills
radio Pick one, all options visible priority, size
checkboxes Pick multiple, all visible features, permissions
toggle On/off switch (UI-friendly boolean) is_active, notifications
boolean Programmatic true/false is_archived, email_verified

Relationship Types

Type Use When Example
lookup Reference another object (soft link) assigned_to → user
master_detail Parent-child with cascade delete line_item → order
tree Self-referencing hierarchy category → category
**lookup vs master_detail:** Use `lookup` when the child can exist independently. Use `master_detail` when deleting the parent should delete all children (e.g., order → line items).

File & Media Types

Type Use When Example
file File upload (set multiple: true for many files) contract, documents
image Image with preview/thumbnail product_photo, screenshots
avatar User profile picture avatar, profile_photo

Computed Types

Type Use When Example
formula Value calculated from other fields full_name = first + last
summary Roll-up aggregate from child records total_amount = sum(items.price)
autonumber Auto-incrementing display ID ticket_number: TICK-0001

Structured Data Types

Type Use When Example
address Postal address with components billing_address, location
location GPS coordinates (lat/lng) office_location, delivery_point
color Hex color value with picker brand_color, label_color
json Arbitrary structured data configuration, metadata
code Code editor (JSON/SQL/JS) query_body, transform

AI & ML Types

Type Use When Example
vector High-dimensional embedding for similarity search (semantic search, RAG) content_embedding

Common Use Case Mapping

Can't find your use case above? Check this table:

Use Case Recommended Type Why
User's full name text Short, single-line, no validation needed
Blog post body richtext Needs formatting (bold, links, images)
Product price currency Money needs currency code and decimal handling
Task assignee lookup References a user record
Invoice line items master_detail Lines should cascade-delete with the invoice
Department hierarchy tree Self-referencing parent → child
Feature flags json Arbitrary key-value configuration
User avatar image Single image with thumbnail support
Support ticket ID autonumber Auto-incrementing human-readable identifier
Total order value summary Roll-up sum of child line item amounts
Discount percentage percent 0–100 range with % display
Terms accepted boolean Simple true/false, no UI toggle needed
Search index vector Used for AI similarity search
OAuth token secret Reversible value stored encrypted at rest

Decision Summary by Question

Question Answer → Field Type
"Can the user type free text?" text, textarea, richtext, markdown, html
"Is it a number I need to calculate with?" number, currency, percent, slider
"Does the user pick from a list?" select, multiselect, radio, checkboxes
"Does it reference another record?" lookup, master_detail, tree
"Is it a file the user uploads?" file, image, avatar
"Is the value computed automatically?" formula, summary, autonumber
"Does it have internal structure?" address, location, color, json, code
"Is it sensitive/secret?" password, secret
"Is it for AI/ML?" vector
**Still unsure?** Start with `text` for strings or `number` for numerics. You can change the field type later, but ObjectStack does not auto-convert existing data: a small set of compatible narrowings (e.g. `text` → `textarea`/`markdown`/`html`/`code`, `date` ↔ `datetime`) pass cleanly, while other type changes are rejected with a `destructive_change` error when you save the updated object — existing values may not convert cleanly. Re-submit the save with `?force=true` to proceed anyway.