CoherenceCOHERENCE

Field Types Reference

Complete API reference for all field types, their configuration schemas, and validation rules

This reference documents all available field types in the Coherence API, including their configuration schemas, validation rules, and example definitions.

Field Definition Structure

Every field in a module follows this base structure:

interface ModuleFieldResource {
  fieldId: string;
  moduleId: string;
  name: string;           // API name (PascalCase)
  slug: string;           // URL-safe identifier (kebab-case)
  label: string;          // Display name
  dataType: string;       // Field type identifier
  config?: FieldConfig;   // Type-specific configuration
  isRequired?: boolean;   // Validation requirement
  isSystem?: boolean;     // System-managed field
  privacyLevel?: "account" | "role" | "private";
  sortOrder?: number;
  createdDateTime: string;
  updatedDateTime: string;
}

Text Fields

text

Single-line text input for short content.

Type identifier: text

Config schema:

interface TextFieldConfig {
  maxLength?: number;     // Maximum characters (default: 255)
  pattern?: string;       // Regex validation pattern
  prefix?: string;        // Static text before value
  suffix?: string;        // Static text after value
}

Example field definition:

{
  "name": "CompanyName",
  "slug": "company-name",
  "label": "Company Name",
  "dataType": "text",
  "isRequired": true,
  "config": {
    "maxLength": 100
  }
}

Validation rules:

  • Value must be a string
  • Length must not exceed maxLength if specified
  • Must match pattern regex if specified

Use cases: Names, titles, short identifiers, SKUs

textarea

Multi-line text input without formatting (long text).

Type identifier: textarea

Config schema:

interface TextareaFieldConfig {
  maxLength?: number;     // Maximum characters (default: 5000)
  rows?: number;          // Initial display height (2-10)
}

Example field definition:

{
  "name": "InternalNotes",
  "slug": "internal-notes",
  "label": "Internal Notes",
  "dataType": "textarea",
  "config": {
    "maxLength": 2000,
    "rows": 4
  }
}

Validation rules:

  • Value must be a string
  • Length must not exceed maxLength if specified

Use cases: Plain text notes, comments, descriptions

rich_text

Full-featured rich text editor with formatting capabilities.

Type identifier: rich_text

Config schema:

interface RichTextFieldConfig {
  richText: {
    enabled: boolean;
    mode: "inline" | "document";
    toolbarPreset: "minimal" | "standard" | "full";
    attachments?: {
      allowImages?: boolean;
      allowFiles?: boolean;
      maxUploadSizeMB?: number;  // 1-100, default: 10
    };
  };
}

Example field definition:

{
  "name": "Description",
  "slug": "description",
  "label": "Description",
  "dataType": "rich_text",
  "config": {
    "richText": {
      "enabled": true,
      "mode": "document",
      "toolbarPreset": "standard",
      "attachments": {
        "allowImages": true,
        "allowFiles": false,
        "maxUploadSizeMB": 10
      }
    }
  }
}

Validation rules:

  • Value must be valid HTML string
  • Attachment sizes must not exceed maxUploadSizeMB

Use cases: Meeting notes, project descriptions, detailed documentation

Rich text fields support paste from Google Docs, Notion, and Word with formatting preserved.

email

Email addresses with validation and multi-value support.

Type identifier: email

Config schema:

interface EmailFieldConfig {
  email?: {
    allowMultiple?: boolean;      // Store multiple emails
    valueTypes?: string[];        // Type labels (e.g., ["Personal", "Work"])
    defaultType?: string;         // Default type for new entries
  };
  emailConfig?: {
    validateEmail?: boolean;      // Strict email validation
  };
}

Multi-value entry structure:

interface EmailEntry {
  id: string;           // Unique entry identifier
  value: string;        // Email address
  label?: string;       // Type label (e.g., "Work")
  isPrimary?: boolean;  // Primary/preferred email
}

Example field definition:

{
  "name": "Email",
  "slug": "email",
  "label": "Email",
  "dataType": "email",
  "isRequired": true,
  "config": {
    "email": {
      "allowMultiple": true,
      "valueTypes": ["Personal", "Work", "Other"],
      "defaultType": "Work"
    }
  }
}

Example value (single):

"[email protected]"

Example value (multi-value):

[
  { "id": "abc123", "value": "[email protected]", "label": "Work", "isPrimary": true },
  { "id": "def456", "value": "[email protected]", "label": "Personal", "isPrimary": false }
]

Validation rules:

  • Must be valid email format when validation enabled
  • Primary email used for communications

Use cases: Contact emails, work emails, personal emails

url

Website links with validation.

Type identifier: url

Config schema:

interface UrlFieldConfig {
  url?: {
    allowMultiple?: boolean;      // Store multiple URLs
    valueTypes?: string[];        // Type labels
    defaultType?: string;         // Default type
  };
}

Example field definition:

{
  "name": "Website",
  "slug": "website",
  "label": "Website",
  "dataType": "url",
  "config": {
    "url": {
      "allowMultiple": true,
      "valueTypes": ["Website", "LinkedIn", "Twitter", "Facebook", "Other"]
    }
  }
}

Validation rules:

  • Must be valid URL format (http:// or https://)

Use cases: Company websites, social profiles, documentation links

phone

Phone numbers with formatting and multi-value support.

Type identifier: phone

Config schema:

interface PhoneFieldConfig {
  phone?: {
    allowMultiple?: boolean;      // Store multiple numbers
    valueTypes?: string[];        // Type labels
    defaultType?: string;         // Default type
  };
  phoneConfig?: {
    validateE164?: boolean;       // Require E.164 format
  };
}

Example field definition:

{
  "name": "Phone",
  "slug": "phone",
  "label": "Phone",
  "dataType": "phone",
  "config": {
    "phone": {
      "allowMultiple": true,
      "valueTypes": ["Mobile", "Work", "Home", "Fax", "Other"],
      "defaultType": "Mobile"
    }
  }
}

Validation rules:

  • E.164 validation when enabled (e.g., +14155551234)
  • Accepts various formats for display

Use cases: Mobile, work phone, fax numbers

address

Structured location data with multi-value support.

Type identifier: address

Config schema:

interface AddressFieldConfig {
  address?: {
    allowMultiple?: boolean;      // Store multiple addresses
    valueTypes?: string[];        // Type labels
    defaultType?: string;         // Default type
  };
}

Structured address value:

interface StructuredAddress {
  street?: string;
  street2?: string;
  city?: string;
  state?: string;
  zip?: string;
  country?: string;
  lat?: number;       // Latitude (auto-filled)
  lng?: number;       // Longitude (auto-filled)
}

Example field definition:

{
  "name": "Address",
  "slug": "address",
  "label": "Address",
  "dataType": "address",
  "config": {
    "address": {
      "allowMultiple": true,
      "valueTypes": ["Home", "Work", "Mailing", "Other"]
    }
  }
}

Example value:

[
  {
    "id": "addr_123",
    "value": {
      "street": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "USA"
    },
    "label": "Work",
    "isPrimary": true
  }
]

Use cases: Office addresses, shipping addresses, locations

Number Fields

number

Integer or decimal numeric values.

Type identifier: number

Config schema:

interface NumberFieldConfig {
  decimals?: number;      // Decimal places (0-10)
  min?: number;           // Minimum value
  max?: number;           // Maximum value
  prefix?: string;        // Display prefix (e.g., "lbs")
  suffix?: string;        // Display suffix (e.g., "units")
  allowNegative?: boolean;
}

Example field definition:

{
  "name": "Quantity",
  "slug": "quantity",
  "label": "Quantity",
  "dataType": "number",
  "config": {
    "decimals": 0,
    "min": 0,
    "max": 10000,
    "suffix": "units"
  }
}

Validation rules:

  • Must be numeric
  • Must be within min/max range if specified
  • Decimal places are enforced

Use cases: Quantities, scores, counts, measurements

currency

Money amounts with currency formatting.

Type identifier: currency

Config schema:

interface CurrencyFieldConfig {
  currency?: {
    defaultCurrency: string;       // ISO code (e.g., "USD")
    allowedCurrencies?: string[];  // Restrict to specific currencies
    precision?: number;            // Decimal places (default: 2)
    showCurrencyCode?: boolean;    // Show code in display
  };
}

Example field definition:

{
  "name": "DealValue",
  "slug": "deal-value",
  "label": "Deal Value",
  "dataType": "currency",
  "config": {
    "currency": {
      "defaultCurrency": "USD",
      "precision": 2,
      "showCurrencyCode": false
    }
  }
}

Example value:

{
  "amount": 15000.00,
  "currency": "USD"
}

Display format: $15,000.00 or 15,000.00 USD

Use cases: Deal values, prices, budgets, revenue

Currency fields can be summed in rollup fields and reports for totals.

Date/Time Fields

date

Calendar date selection.

Type identifier: date

Config schema:

interface DateFieldConfig {
  format?: string;        // Display format
  minDate?: string;       // Minimum date (ISO)
  maxDate?: string;       // Maximum date (ISO)
}

Example field definition:

{
  "name": "DueDate",
  "slug": "due-date",
  "label": "Due Date",
  "dataType": "date",
  "isRequired": true
}

Value format: ISO 8601 date string (2024-01-15)

Use cases: Due dates, start dates, birthdays

time

Time-only field without date component.

Type identifier: time

Config schema:

interface TimeFieldConfig {
  time?: {
    format12h?: boolean;    // 12-hour vs 24-hour format
  };
}

Example field definition:

{
  "name": "OpeningTime",
  "slug": "opening-time",
  "label": "Opening Time",
  "dataType": "time",
  "config": {
    "time": {
      "format12h": true
    }
  }
}

Value format: ISO 8601 time string (09:00:00)

Use cases: Business hours, daily schedules, recurring times

date_range

Start and end date pair for durations.

Type identifier: date_range

Config schema:

interface DateRangeFieldConfig {
  dateRange?: {
    includeTime?: boolean;    // Include time component
  };
}

Example field definition:

{
  "name": "ProjectDuration",
  "slug": "project-duration",
  "label": "Project Duration",
  "dataType": "date_range",
  "config": {
    "dateRange": {
      "includeTime": false
    }
  }
}

Value format:

{
  "start": "2024-01-15",
  "end": "2024-03-31"
}

Use cases: Project timelines, event durations, booking periods

duration

Time span in hours, minutes, seconds.

Type identifier: duration

Config schema:

interface DurationFieldConfig {
  duration?: {
    format: "hm" | "hms" | "decimal";  // Display format
  };
}

Example field definition:

{
  "name": "TimeSpent",
  "slug": "time-spent",
  "label": "Time Spent",
  "dataType": "duration",
  "config": {
    "duration": {
      "format": "hm"
    }
  }
}

Value format: Duration in seconds (stored) or formatted string

Display formats:

  • hm: 2h 30m
  • hms: 2h 30m 45s
  • decimal: 2.5h

Use cases: Time tracking, meeting lengths, task estimates

Selection Fields

select

Single selection from a predefined list.

Type identifier: select

Config schema:

interface SelectFieldConfig {
  options: Array<string | SelectOption>;
  select?: {
    defaultOptionSlug?: string;   // Pre-selected value
  };
}
 
interface SelectOption {
  value: string;    // Storage value (slug)
  label?: string;   // Display label
  color?: string;   // Chip color (hex or preset)
}

Example field definition:

{
  "name": "Status",
  "slug": "status",
  "label": "Status",
  "dataType": "select",
  "config": {
    "options": [
      { "value": "new", "label": "New", "color": "#3b82f6" },
      { "value": "in-progress", "label": "In Progress", "color": "#f59e0b" },
      { "value": "completed", "label": "Completed", "color": "#22c55e" }
    ],
    "select": {
      "defaultOptionSlug": "new"
    }
  }
}

Validation rules:

  • Value must match one of the configured option values
  • Required fields must have a value selected

Use cases: Status, priority, type, category

multi_select

Multiple selections from a predefined list (tags).

Type identifier: multi_select

Config schema:

interface MultiSelectFieldConfig {
  options: Array<string | SelectOption>;
  multiSelect?: {
    defaultOptionSlugs?: string[];  // Pre-selected values
    maxItems?: number;              // Maximum selections
    allowFreeForm?: boolean;        // Allow adding new options
  };
}

Example field definition:

{
  "name": "Tags",
  "slug": "tags",
  "label": "Tags",
  "dataType": "multi_select",
  "config": {
    "options": [
      { "value": "hot-lead", "label": "Hot Lead", "color": "#ef4444" },
      { "value": "vip", "label": "VIP", "color": "#8b5cf6" },
      { "value": "partner", "label": "Partner", "color": "#06b6d4" }
    ],
    "multiSelect": {
      "maxItems": 5,
      "allowFreeForm": true
    }
  }
}

Value format: Array of option values

["hot-lead", "vip"]

Use cases: Tags, categories, skills, features

boolean

Simple true/false toggle (checkbox).

Type identifier: boolean

Config schema:

interface BooleanFieldConfig {
  default?: boolean;      // Default value
  label?: string;         // Custom display text
}

Example field definition:

{
  "name": "IsActive",
  "slug": "is-active",
  "label": "Is Active",
  "dataType": "boolean",
  "config": {
    "default": true
  }
}

Use cases: Flags, yes/no questions, feature toggles

Reference Fields

reference

Link to records in another module.

Type identifier: reference

Config schema:

interface ReferenceFieldConfig {
  reference: {
    targetType: "module" | "user" | "team";
    selectionMode: "single" | "multi";
    allowedModuleSlugs?: string[];           // Target modules
    allowedRoleSlugs?: string[];             // Filter by roles (user type)
    allowedTeamSlugs?: string[];             // Filter by teams (user type)
    includeArchivedTargets?: boolean;
    includeInactiveUsers?: boolean;
    defaultAssignToCurrentUser?: boolean;    // For user references
    allowInlineCreate?: boolean;             // Allow creating new records inline
    dependency?: {
      dependsOnFieldSlug: string;            // Tiered filtering
      filterExpression?: string;
    };
  };
}

Example field definition (module reference):

{
  "name": "Company",
  "slug": "company",
  "label": "Company",
  "dataType": "reference",
  "config": {
    "reference": {
      "targetType": "module",
      "selectionMode": "single",
      "allowedModuleSlugs": ["accounts"],
      "allowInlineCreate": true
    }
  }
}

Example field definition (user reference):

{
  "name": "Owner",
  "slug": "owner",
  "label": "Owner",
  "dataType": "reference",
  "config": {
    "reference": {
      "targetType": "user",
      "selectionMode": "single",
      "defaultAssignToCurrentUser": true,
      "includeInactiveUsers": false
    }
  }
}

Value format (single):

{
  "recordId": "rec_abc123",
  "displayName": "Acme Corporation"
}

Value format (multi):

[
  { "recordId": "rec_abc123", "displayName": "Acme Corporation" },
  { "recordId": "rec_def456", "displayName": "TechCorp Inc" }
]

Use cases: Linking contacts to companies, assigning owners, relationships

Reference fields support tiered filtering through the dependency config, allowing cascading selections (e.g., select team first, then team members).

person

Link to workspace team members (simplified user reference).

Type identifier: person

Config schema:

interface PersonFieldConfig {
  person?: {
    allowMultiple?: boolean;
    includeInactiveUsers?: boolean;
  };
}

Example field definition:

{
  "name": "AssignedTo",
  "slug": "assigned-to",
  "label": "Assigned To",
  "dataType": "person",
  "config": {
    "person": {
      "allowMultiple": true,
      "includeInactiveUsers": false
    }
  }
}

Value format:

{
  "userId": "usr_abc123",
  "displayName": "John Smith",
  "email": "[email protected]",
  "avatar": "https://..."
}

Use cases: Assignees, reviewers, participants

parent_record

Self-referencing relationship for hierarchies.

Type identifier: parent_record

Config schema:

interface ParentRecordFieldConfig {
  parentRecord?: {
    maxDepth?: number;      // Maximum nesting depth (1-10, default: 5)
    preventCycles?: true;   // Always true - cycles are prevented
  };
}

Example field definition:

{
  "name": "ParentTask",
  "slug": "parent-task",
  "label": "Parent Task",
  "dataType": "parent_record",
  "config": {
    "parentRecord": {
      "maxDepth": 5
    }
  }
}

Use cases: Task subtasks, category hierarchies, organizational structures

Computed Fields

formula

Calculate values from other fields.

Type identifier: formula

Config schema:

interface FormulaFieldConfig {
  formula: {
    expression: string;                         // Formula expression
    resultType: "text" | "number" | "date" | "boolean";
    format?: string;                            // Display format
    decimalPlaces?: number;                     // For number results
    referencedFields?: string[];                // Auto-populated dependencies
  };
}

Example field definition:

{
  "name": "FullName",
  "slug": "full-name",
  "label": "Full Name",
  "dataType": "formula",
  "config": {
    "formula": {
      "expression": "CONCAT({first-name}, \" \", {last-name})",
      "resultType": "text",
      "referencedFields": ["first-name", "last-name"]
    }
  }
}

Formula syntax:

Fields are referenced using {field-slug} notation.

Available functions:

// Text
CONCAT(value1, value2, ...)
UPPER(text)
LOWER(text)
LEFT(text, count)
RIGHT(text, count)
TRIM(text)
LEN(text)

// Math
SUM(value1, value2, ...)
ROUND(number, decimals)
ABS(number)
FLOOR(number)
CEIL(number)
MIN(value1, value2, ...)
MAX(value1, value2, ...)

// Date
DATEDIFF(date1, date2)
DATEADD(date, amount, unit)
TODAY()
NOW()
YEAR(date)
MONTH(date)
DAY(date)

// Logic
IF(condition, trueValue, falseValue)
AND(condition1, condition2, ...)
OR(condition1, condition2, ...)
NOT(condition)
ISBLANK(field)

Use cases: Calculated totals, derived values, conditional status

rollup

Aggregate data from linked records.

Type identifier: rollup

Config schema:

interface RollupFieldConfig {
  rollup: {
    linkedFieldSlug: string;                  // Reference field to aggregate from
    aggregateFieldSlug?: string | null;       // Field to aggregate (null for COUNT)
    aggregation: RollupAggregation;
    filterCriteria?: Record<string, unknown>; // Filter linked records
    decimalPlaces?: number;
    format?: string;
  };
}
 
type RollupAggregation =
  | "COUNT"     // Count non-empty values
  | "COUNTALL"  // Count all records
  | "COUNTA"    // Count unique values
  | "SUM"       // Sum numeric values
  | "AVG"       // Average numeric values
  | "MIN"       // Minimum value
  | "MAX";      // Maximum value

Example field definition:

{
  "name": "TotalDealValue",
  "slug": "total-deal-value",
  "label": "Total Deal Value",
  "dataType": "rollup",
  "config": {
    "rollup": {
      "linkedFieldSlug": "deals",
      "aggregateFieldSlug": "deal-value",
      "aggregation": "SUM",
      "decimalPlaces": 2
    }
  }
}

Use cases: Total deal value from linked deals, contact count per company, average order value

autonumber

Automatic sequential numbering for records.

Type identifier: autonumber

Config schema:

interface AutonumberFieldConfig {
  autonumber?: {
    formatType?: "none" | "prefix" | "suffix" | "both";
    prefix?: string;          // Text before number (e.g., "INV-")
    suffix?: string;          // Text after number (e.g., "-2024")
    padding?: number;         // Zero-pad to length (e.g., 5 = "00001")
    startFrom?: number;       // Initial value (default: 1)
    sequenceByType?: Record<string, {
      prefix: string;
      sequenceName?: string;
    }>;                       // Different sequences per record type
    typeFieldSlug?: string;   // Field that determines sequence
  };
}

Example field definition:

{
  "name": "InvoiceNumber",
  "slug": "invoice-number",
  "label": "Invoice #",
  "dataType": "autonumber",
  "config": {
    "autonumber": {
      "formatType": "prefix",
      "prefix": "INV-",
      "padding": 5,
      "startFrom": 1
    }
  }
}

Generated values: INV-00001, INV-00002, INV-00003, ...

Behavior:

  • Automatically assigned on record creation
  • Unique and never reused
  • Cannot be manually edited
  • Gaps preserved when records deleted

Use prefixes to identify record types at a glance. Combine with year suffixes for date-aware numbering (e.g., ORD-2024-00001).

Special Fields

image

Image upload with gallery and lightbox.

Type identifier: image

Config schema:

interface ImageFieldConfig {
  image?: {
    multiple?: boolean;                      // Allow multiple images
    maxImages?: number;                      // Maximum uploads (default: 10)
    maxSizeKB?: number;                      // Per-file size limit (default: 5120)
    showInGrid?: "thumbnail" | "icon" | "none";
  };
}

Example field definition:

{
  "name": "ProductImages",
  "slug": "product-images",
  "label": "Product Images",
  "dataType": "image",
  "config": {
    "image": {
      "multiple": true,
      "maxImages": 10,
      "maxSizeKB": 5120,
      "showInGrid": "thumbnail"
    }
  }
}

Supported formats: JPG, PNG, GIF, WebP

Use cases: Product photos, profile pictures, attachments

rating

Star or heart-based rating input.

Type identifier: rating

Config schema:

interface RatingFieldConfig {
  rating?: {
    maxRating?: number;       // Number of stars (1-10, default: 5)
    allowHalf?: boolean;      // Allow half ratings
    showNumber?: boolean;     // Display numeric value
    icon?: "star" | "heart";  // Rating icon
  };
}

Example field definition:

{
  "name": "CustomerRating",
  "slug": "customer-rating",
  "label": "Customer Rating",
  "dataType": "rating",
  "config": {
    "rating": {
      "maxRating": 5,
      "allowHalf": true,
      "showNumber": true,
      "icon": "star"
    }
  }
}

Value format: Number (e.g., 4.5)

Use cases: Customer ratings, quality scores, satisfaction levels

progress

Visual progress bar with percentage.

Type identifier: progress

Config schema:

interface ProgressFieldConfig {
  progress?: {
    showPercentage?: boolean;
    colorThresholds?: {
      [threshold: number]: string;  // Color at threshold (e.g., { 33: "red", 66: "yellow", 100: "green" })
    } | null;
  };
}

Example field definition:

{
  "name": "Completion",
  "slug": "completion",
  "label": "Completion",
  "dataType": "progress",
  "config": {
    "progress": {
      "showPercentage": true,
      "colorThresholds": {
        "33": "#ef4444",
        "66": "#f59e0b",
        "100": "#22c55e"
      }
    }
  }
}

Value format: Number 0-100 (percentage)

Use cases: Task progress, goal completion, project status

social_profile

Social media profiles with platform detection.

Type identifier: social_profile

Config schema:

interface SocialProfileFieldConfig {
  platforms?: string[];     // Limit to specific platforms
  allowMultiple?: boolean;  // Allow multiple profiles
}

Supported platforms:

  • LinkedIn, Twitter/X, Facebook
  • Instagram, GitHub, YouTube
  • TikTok, Dribbble, Behance
  • Custom websites

Example field definition:

{
  "name": "SocialLinks",
  "slug": "social-links",
  "label": "Social Links",
  "dataType": "social_profile"
}

Features:

  • Auto-detects platform from URL
  • Displays brand-colored icons
  • Extracts usernames

Use cases: Contact social links, influencer profiles

API Examples

Creating a field

POST /v1/modules/{moduleSlug}/fields
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
 
{
  "name": "Priority",
  "slug": "priority",
  "label": "Priority",
  "dataType": "select",
  "isRequired": false,
  "config": {
    "options": [
      { "value": "low", "label": "Low", "color": "#22c55e" },
      { "value": "medium", "label": "Medium", "color": "#f59e0b" },
      { "value": "high", "label": "High", "color": "#ef4444" }
    ],
    "select": {
      "defaultOptionSlug": "medium"
    }
  }
}

Updating a field

PATCH /v1/modules/{moduleSlug}/fields/{fieldId}
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
 
{
  "label": "Priority Level",
  "config": {
    "options": [
      { "value": "low", "label": "Low", "color": "#22c55e" },
      { "value": "medium", "label": "Medium", "color": "#f59e0b" },
      { "value": "high", "label": "High", "color": "#ef4444" },
      { "value": "urgent", "label": "Urgent", "color": "#dc2626" }
    ]
  }
}

Setting field values on records

POST /v1/modules/{moduleSlug}/records
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
 
{
  "name": "John Smith",
  "email": [
    { "id": "email_1", "value": "[email protected]", "label": "Work", "isPrimary": true }
  ],
  "company": { "recordId": "rec_abc123" },
  "status": "active",
  "tags": ["vip", "partner"],
  "deal-value": { "amount": 50000, "currency": "USD" }
}

Next: Learn about Records API or explore Filters and Sorting.