Semantic Types Overview

Semantic types are high-level column definitions with built-in validation, formatting, and sensible defaults. They provide a consistent, type-safe way to define common data patterns.

Quick Reference

All semantic types are available via the col.* global in your schema files.

Identity & Authentication

Type	Base Type	Details
`col.id()`	UUID	Primary key with auto-generation
`col.email()`	`string(255)`	Email validation pattern
`col.username()`	`string(50)`	Lowercase alphanumeric + underscores
`col.password_hash()`	`string(255)`	Hidden from API exports
`col.phone()`	`string(50)`	E.164 international format
`col.token()`	`string(64)`	For API keys and session tokens

Text Content

Type	Base Type	Details
`col.name()`	`string(100)`	Person/entity names
`col.title()`	`string(200)`	Article/page titles
`col.slug()`	`string(255)`	URL-safe, unique, lowercase
`col.summary()`	`string(500)`	Short descriptions
`col.code()`	`string(20)`	SKUs, codes (uppercase pattern)
`col.body()`	`text`	Long-form content
`col.html()`	`text`	HTML content with format hint
`col.markdown()`	`text`	Markdown formatted content

Numbers & Money

Type	Base Type	Details
`col.money()`	`decimal(19,4)`	Currency amounts, min(0)
`col.percentage()`	`decimal(5,2)`	0-100 range, two decimal places
`col.counter()`	`integer`	Auto-defaults to 0
`col.quantity()`	`integer`	Non-negative integers
`col.rating()`	`decimal(2,1)`	0-5 rating scale
`col.duration()`	`integer`	Duration in seconds, min(0)

URLs & Network

Type	Base Type	Details
`col.url()`	`string(2048)`	Full URLs with scheme
`col.ip()`	`string(45)`	IPv4 or IPv6 with validation
`col.ipv4()`	`string(15)`	IPv4 only with validation
`col.ipv6()`	`string(45)`	IPv6 only with validation
`col.user_agent()`	`string(500)`	Browser user agent strings

Internationalization

Type	Base Type	Details
`col.country()`	`string(2)`	ISO 3166-1 alpha-2 (US)
`col.currency()`	`string(3)`	ISO 4217 (USD)
`col.locale()`	`string(10)`	BCP 47 (en-US)
`col.timezone()`	`string(50)`	IANA timezone names

Media & Display

Type	Base Type	Details
`col.color()`	`string(7)`	Hex format (#FF5733)

Boolean Flags

Type	Base Type	Details
`col.flag()`	`boolean`	Defaults to `false`
`col.flag(true)`	`boolean`	Defaults to `true`

Usage Patterns

Basic Example

export default table({
  id: col.id(),
  title: col.title(),
  slug: col.slug(),
  body: col.body(),
  published: col.flag(),
}).timestamps();

With Modifiers

Semantic types can be combined with modifiers:

export default table({
  id: col.id(),
  email: col.email().unique(),
  username: col.username().unique(),
  password_hash: col.password_hash(),
  bio: col.text().optional(),
  website: col.url().optional(),
  is_active: col.flag(true),
}).timestamps();

E-Commerce Example

export default table({
  id: col.id(),
  name: col.name(),
  slug: col.slug(),
  description: col.body().optional(),
  sku: col.code().unique(),
  price: col.money(),
  stock: col.quantity(),
  rating: col.rating().optional(),
  is_featured: col.flag(),
}).timestamps();

Validation & Constraints

Semantic types include built-in validation:

email: RFC 5322 compliant pattern
phone: E.164 international format (^\+?[1-9]\d{1,14}$)
url: Must include scheme (http/https)
slug: Lowercase with hyphens (^[a-z0-9]+(?:-[a-z0-9]+)*$)
username: Lowercase alphanumeric + underscores, min 3 chars
code: Uppercase alphanumeric (^[A-Z0-9]+$)
color: 6-digit hex with # prefix (^#[0-9A-Fa-f]{6}$)

Hidden Fields

Some types are automatically excluded from API exports:

col.password_hash() - marked as x-hidden in OpenAPI

This prevents sensitive data from appearing in generated API documentation or client-side types.

OpenAPI Integration

Semantic types automatically set OpenAPI format hints:

email: col.email()
// OpenAPI: { type: "string", format: "email", pattern: "..." }

url: col.url()
// OpenAPI: { type: "string", format: "uri", pattern: "..." }

money: col.money()
// OpenAPI: { type: "number", format: "decimal", minimum: 0 }

When to Use Low-Level Types

Use low-level types when:

You need a custom string length not provided by semantic types
The semantic validation pattern doesn’t match your requirements
You’re working with domain-specific data that doesn’t fit standard patterns

// Custom case: use low-level types
export default table({
  id: col.id(),
  custom_code: col.string(15).pattern(/^CUST-[A-Z]{4}-\d{6}$/),
  metadata: col.json(),
});

Implementation Details

All semantic types are defined in a centralized registry (internal/runtime/semantic.go) and include:

Base type (string, text, integer, decimal, boolean)
Length/precision constraints
Validation patterns (regex)
Min/Max constraints
Default values
Format hints for OpenAPI
Hidden flag for sensitive data

This ensures consistency across migrations, exports, and documentation.