DenchClaw Field Types: Complete Reference Guide

DenchClaw supports a rich set of field types that cover everything you'd find in a modern CRM — from simple text and numbers to relational links, executable action buttons, and rich markdown documents. This guide covers every field type, how it's stored, how it renders, and when to use it.

Scalar Field Types#

text#

The most basic field type. Stores a plain string value.

Use for: Names, titles, descriptions, notes that don't need formatting, addresses, any freeform text.

YAML definition:

- name: Full Name
  type: text
  required: true

Storage: Stored as a plain string in entry_fields.value.

UI rendering: Single-line text input. Use richtext if you need multi-line with formatting.

number#

Stores a numeric value. Supports optional format modifiers.

Use for: Revenue, employee count, deal size, years of experience, rating, phone extension, priority scores.

YAML definition:

- name: Deal Value
  type: number
  format: currency   # Options: currency, percent, integer, decimal
  currency: USD

Storage: Stored as a string in entry_fields.value, parsed to float for queries.

UI rendering: Numeric input with format-appropriate display (e.g., "$25,000" for currency).

date#

Stores a date value (without time). For timestamps, use datetime.

Use for: Close date, birthday, contract expiry, last contact date, start date, deadline.

YAML definition:

- name: Contract End Date
  type: date

Storage: ISO 8601 date string (YYYY-MM-DD) in entry_fields.value.

UI rendering: Date picker. Used as the date field for Calendar and Timeline views.

datetime#

Stores a date + time value.

Use for: Meeting timestamps, created_at logs, scheduled reminders.

YAML definition:

- name: Meeting Time
  type: datetime

Storage: ISO 8601 datetime string.

email#

A validated email address field.

Use for: Primary email, billing email, contact email.

YAML definition:

- name: Email Address
  type: email

Storage: String. Validated as email format on input.

UI rendering: Renders as a clickable mailto: link in table view.

phone#

A phone number field with optional formatting.

Use for: Mobile, office phone, direct line.

YAML definition:

- name: Phone Number
  type: phone

Storage: String. Stored as-entered (no normalization by default).

UI rendering: Renders as a clickable tel: link on mobile.

url#

A validated URL field.

Use for: Website, LinkedIn, portfolio, GitHub profile, Calendly link.

YAML definition:

- name: Website
  type: url

Storage: String. Validated as URL format on input.

UI rendering: Renders as a clickable external link.

boolean#

A true/false checkbox field.

Use for: Active status, has review, needs follow-up, email opted in.

YAML definition:

- name: Has Board Seat
  type: boolean
  default: false

Storage: "true" or "false" string.

UI rendering: Checkbox in table and form views.

Categorical Field Types#

enum#

A single-select dropdown with a predefined list of options.

Use for: Status, stage, priority, type, category — any field where only one value applies.

YAML definition:

- name: Status
  type: enum
  options:
    - Lead
    - Active
    - Churned
    - Prospect

Storage: String (the selected option value).

UI rendering: Dropdown in form view, colored badge in table view (colors can be configured in statuses:).

Special behavior: When an object has a kanbanField pointing to an enum field, that enum's values become the Kanban columns.

tags#

A multi-select field where multiple values can be applied simultaneously.

Use for: Skills, technologies, interests, categories, labels — any field where multiple values apply.

YAML definition:

- name: Skills
  type: tags
  options:
    - Python
    - React
    - Machine Learning
    - SQL

Storage: JSON array string (e.g., ["Python","React"]).

UI rendering: Multi-select input with chips/badges. Filterable.

Relational Field Types#

relation#

Links an entry to another object. Creates a foreign key relationship between objects.

Use for: Linking a deal to a company, linking a task to a project, linking a contact to their employer.

YAML definition:

- name: Company
  type: relation
  related_object: company
  relation_type: many_to_one   # or one_to_many, many_to_many

Storage: UUID of the related entry in entry_fields.value.

UI rendering: Searchable dropdown showing all entries from the related object. Renders as a linked label in table view.

Query behavior: Relation fields are denormalized in PIVOT views — the display label of the related entry is shown, not the UUID.

Rich Content Field Types#

richtext#

A full rich-text editor supporting markdown formatting.

Use for: Detailed notes, client history, meeting summaries, long-form descriptions.

YAML definition:

- name: Notes
  type: richtext

Storage: Markdown string in entry_fields.value.

UI rendering: Rich text editor with markdown support (bold, italic, lists, code blocks, headers). Rendered as formatted HTML in read mode.

file#

A file attachment or reference.

Use for: Contract PDFs, headshots, logos, reference documents.

YAML definition:

- name: Contract
  type: file

Storage: File path or URL string.

UI rendering: File upload input; renders as a downloadable link.

Special Field Types#

action#

An action field adds a button to every row in table view. Clicking the button executes a configured script.

Use for: "Send Email," "Enrich with Apollo," "Run Credit Check," "Open in CRM," custom one-click workflows.

YAML definition:

- name: Send Follow-up
  type: action
  script: scripts/send-followup.sh
  label: Send Email
  icon: mail

Script behavior: The script receives all of the entry's field values as environment variables and can:

• Stream NDJSON status messages back to the UI
• Update the entry with new data
• Trigger webhooks
• Call external APIs
• Launch browser automation

Scripts can be shell scripts, Python scripts, or Node.js scripts.

UI rendering: Button in each table row. Clicking shows a streaming response panel as the script executes.

user#

A user reference field (reserved for multi-user workspaces).

Use for: Assigned to, created by, owner.

YAML definition:

- name: Owner
  type: user

Storage: User ID string.

UI rendering: User avatar and name (when multi-user is enabled).

Field Configuration Options#

All fields support these common options:

- name: Field Name
  type: text
  required: true       # Validation: required on create
  default: ""          # Default value for new entries
  hidden: false        # Hide from table view columns
  width: 200           # Column width in pixels (table view)
  description: "Help text shown in form view"

Enum fields additionally support:

options:
  - name: Active
    color: green
  - name: Inactive
    color: gray
  - name: Prospect
    color: blue

Adding Fields via Natural Language#

Rather than editing YAML manually, you can ask DenchClaw to add fields:

"Add a 'Priority' enum field to the Deals object with options High, Medium, and Low."

"Add a phone number field and a LinkedIn URL field to the People object."

"Add a relation field to the Tasks object linking to Projects."

DenchClaw updates both the DuckDB schema and the .object.yaml file atomically.

See also: DenchClaw Object System for how objects and fields fit together, and DenchClaw Saved Views for filtering by any field type.

Frequently Asked Questions#

Can I create custom field types beyond the built-in ones?#

DenchClaw's field system is extensible. The most flexible approach is using richtext for unstructured data or text with a consistent format convention. True custom field type plugins are on the roadmap.

What's the difference between richtext and the entry document?#

A richtext field is a field column on the entry — it appears in the table and form view. The entry document is a separate, full-page markdown file linked to the entry via the documents table. Use richtext for short structured notes; use the entry document for long-form content that deserves its own page.

How do I change a field type after I've added data?#

DenchClaw supports field type migrations for compatible conversions (e.g., text → email, text → url). For incompatible type changes, you'll need to create a new field and migrate data manually. The AI can help: "I want to change the Status field from text to enum — here are the values that currently exist."

Can I reorder fields in the form view?#

Yes. Edit the fields: section of the .object.yaml — fields render in the order they appear in the YAML. Or ask DenchClaw: "Move the Priority field above the Notes field in the form view."

How do relation fields work with deletion?#

When you delete a related entry, relation field values pointing to it are set to NULL. DenchClaw doesn't cascade deletes automatically — you won't lose your deals when you delete a company, but the company relation on those deals will be empty.

Ready to try DenchClaw? Install in one command: npx denchclaw. Full setup guide →