Field Types

Contentrain supports 27 field types organized into 7 categories. Each field type has specific validation rules, a JSON storage type, and UI representation.

Field Definition Schema

Every field in a model definition follows this schema:

interface FieldDef {
  type: string                    // One of the 27 types
  required?: boolean              // Field is required
  unique?: boolean                // Value must be unique in collection
  min?: number                    // Min length (string), min value (number), min items (array)
  max?: number                    // Max length (string), max value (number), max items (array)
  pattern?: string                // Regex validation pattern
  options?: string[]              // Valid values for select type
  default?: unknown               // Default value (omitted from JSON when matched)
  description?: string            // Human-readable description
  model?: string | string[]       // Relation target model(s)
  items?: string | FieldDef       // Array item type or definition
  fields?: Record<string, FieldDef>  // Nested object fields
  accept?: string                 // MIME type filter for media fields
}

Type Reference

Text Types

Type	JSON Storage	Description	Validation
string	string	Single-line text	min/max length, pattern regex
text	string	Multi-line plain text	min/max length, pattern regex
markdown	string	Markdown-formatted text	min/max length
richtext	string	HTML rich text	min/max length
code	string	Code snippet	min/max length
slug	string	URL slug	Lowercase, alphanumeric, hyphens only (/^[a-z0-9]+(?:-[a-z0-9]+)*$/)

Example field definition:

{
  "title": {
    "type": "string",
    "required": true,
    "min": 1,
    "max": 200,
    "description": "Blog post title"
  }
}

Number Types

Type	JSON Storage	Description	Validation
number	number	Any number (int or float)	min/max range
integer	number	Integer only	Must be Number.isInteger(), min/max range
decimal	number	Floating-point number	min/max range
percent	number	Percentage (0-100)	Must be between 0 and 100
rating	number	Star rating (1-5)	Must be integer between 1 and 5

Example:

{
  "price": { "type": "decimal", "required": true, "min": 0 },
  "rating": { "type": "rating" },
  "progress": { "type": "percent", "default": 0 }
}

Boolean Type

Type	JSON Storage	Description	Validation
boolean	boolean	True/false toggle	Must be true or false

Date Types

Type	JSON Storage	Description	Validation
date	string	Date (ISO format)	Must be valid date string (Date.parse())
datetime	string	Date + time (ISO format)	Must be valid datetime string

Example values:

{
  "publishDate": "2026-01-15",
  "createdAt": "2026-01-15T12:00:00.000Z"
}

Contact Types

Type	JSON Storage	Description	Validation
email	string	Email address	Regex: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ (warning-level)
url	string	URL	Must start with http://, https://, or / (warning-level)
phone	string	Phone number	min/max length, pattern regex

Visual Types

Type	JSON Storage	Description	Validation
color	string	Hex color code	Must match /^#[0-9a-fA-F]{6}$/
icon	string	Icon identifier	min/max length

Example:

{
  "brandColor": "#3B82F6",
  "menuIcon": "icon-[annon--home-2]"
}

Selection Type

Type	JSON Storage	Description	Validation
select	string	Single value from options	Must be one of defined options[]

Example:

{
  "status": {
    "type": "select",
    "options": ["draft", "review", "published"],
    "default": "draft",
    "required": true
  }
}

Media Types

Type	JSON Storage	Description	Validation
image	string	Image file path	Must be a string (file path)
video	string	Video file path	Must be a string (file path)
file	string	Generic file path	Must be a string (file path)

Media field values store the path to the asset in R2 storage:

{
  "cover": "media/original/abc123.webp",
  "thumbnail": "media/thumbnail/abc123.webp"
}

The accept property can filter allowed MIME types:

{
  "avatar": {
    "type": "image",
    "accept": "image/png,image/jpeg,image/webp"
  }
}

Relation Types

Type	JSON Storage	Description	Validation
relation	string or object	Reference to another entry	Must be entry ID, slug, or { model, ref } for polymorphic
relations	string[]	Array of references	Each item must be string ID/slug

Single Relation

{
  "author": {
    "type": "relation",
    "model": "team-members",
    "required": true
  }
}

Value: "a1b2c3d4e5f6" (entry ID for collections) or "john-doe" (slug for documents)

Polymorphic Relation

When model is an array, the value must be an object:

{
  "relatedContent": {
    "type": "relation",
    "model": ["blog-post", "page"]
  }
}

Value: { "model": "blog-post", "ref": "a1b2c3d4e5f6" }

Multi-Relation

{
  "tags": {
    "type": "relations",
    "model": "tags",
    "min": 1,
    "max": 10
  }
}

Value: ["tag-id-1", "tag-id-2", "tag-id-3"]

Structured Types

Type	JSON Storage	Description	Validation
object	object	Nested object	Validates nested fields (max 2 levels deep)
array	array	Array of items	min/max count, validates items type

Object Field

{
  "address": {
    "type": "object",
    "fields": {
      "street": { "type": "string", "required": true },
      "city": { "type": "string", "required": true },
      "zip": { "type": "string", "pattern": "^\\d{5}$" }
    }
  }
}

Array Field (Simple)

{
  "tags": {
    "type": "array",
    "items": "string",
    "min": 1,
    "max": 20
  }
}

Array Field (Object Items)

{
  "socialLinks": {
    "type": "array",
    "items": {
      "type": "object",
      "fields": {
        "platform": { "type": "select", "options": ["twitter", "github", "linkedin"] },
        "url": { "type": "url", "required": true }
      }
    },
    "max": 5
  }
}

System Fields

These fields are managed by Studio and must never be included in save_content data:

Field	Description
id	Entry ID (12-char hex, auto-generated)
slug	Document slug (set via slug parameter, not in data)
status	Publish status (draft, published, archived)
source	Origin indicator (mcp-local, studio, etc.)

Validation Summary

Check	Applies To	Severity
Required	All types	error
Unique	All types (collection-level)	error
Min/Max length	string, text, markdown, richtext, code, phone	error
Min/Max value	number, integer, decimal	error
Min/Max items	array, relations	error
Pattern (regex)	string, text, phone	error
Options list	select	error
Email format	email	warning
URL format	url	warning
Slug format	slug	error
Color format	color	error
Date validity	date, datetime	error
Integer check	integer, rating	error
Percent range	percent	error
Rating range	rating	error
Relation target	relation, relations	warning (referential integrity)
Nested validation	object, array (object items)	error

Related Pages

• Contentrain Format -- how fields are stored in model files
• Content Engine -- validation implementation
• Agent System -- how the agent uses field definitions