Tipos de campo

Cada tipo de campo que puedes declarar en un objeto — qué almacena, qué opciones acepta y cómo se manifiesta en REST, Console y el AI Builder.

48 tipos de campo integrados, agrupados por familia. El esquema Zod completo está en packages/spec/src/data/field.zod.ts — esta página es un resumen práctico.

Propiedades fundamentales (cada campo)

Propiedad	Tipo	Predeterminado	Propósito
`name`	string (snake_case)	—	Identificador de máquina — segmento de ruta REST, columna SQL
`label`	string	—	Etiqueta de visualización en Console
`type`	FieldType	—	Consulta las tablas de tipos a continuación
`required`	boolean	`false`	Restricción NOT NULL
`unique`	boolean	`false`	Índice único
`searchable`	boolean	`false`	Indexado para `/api/v1/search`
`multiple`	boolean	`false`	Almacena un arreglo de valores
`defaultValue`	unknown	—	Valor inicial (literal o CEL)
`hidden`	boolean	`false`	Oculta de las vistas predeterminadas de Console
`readonly`	boolean	`false`	Deshabilita en formularios
`system`	boolean	`false`	Inyectado automáticamente (id, created_at, …)
`externalId`	boolean	`false`	Apto para upsert mediante clave externa
`inlineHelpText`	string	—	Texto de información sobre herramientas / ayuda
`conditionalRequired`	predicado `P`	—	Obligatorio cuando el CEL es verdadero
`trackHistory`	boolean	`false`	Muestra los cambios de valor como entradas legibles en la línea de tiempo de actividad del registro (ADR-0052)

Familia de texto

Tipo	Para qué usarlo	Opciones clave
`text`	cadenas cortas	`maxLength`, `minLength`
`textarea`	varias líneas	`maxLength`
`email`	correo electrónico	validado por formato; en minúsculas
`url`	URL	validado por formato
`phone`	teléfono	E.164
`password`	secretos de un solo sentido	con hash por el subsistema de autenticación; nunca devuelto por GET
`secret`	secretos reversibles (claves de API, tokens, contraseñas de BD)	cifrado en reposo mediante el proveedor de criptografía, almacenado como una referencia opaca, enmascarado al leer. Fail-closed: sin un proveedor configurado, las escrituras lanzan un error en lugar de persistir texto plano
`markdown`	cuerpo markdown	renderizado en la vista previa de Console
`html`	HTML saneado	DOMPurify al escribir
`richtext`	WYSIWYG	editor de Console + JSON serializado

Números

Tipo	Para qué usarlo	Opciones clave
`number`	flotantes	`min`, `max`, `precision`, `scale`
`currency`	dinero	`currencyConfig: { precision, currencyMode: 'fixed' \| 'dynamic', defaultCurrency }`
`percent`	0–100 %	`min`, `max`, `scale`

integer y decimal no son tipos separados — usa number con scale: 0 para enteros, precision+scale para decimales fijos.

Fecha / hora

Tipo	Almacena	Notas
`date`	fecha de calendario	sin zona horaria
`datetime`	instante	UTC
`time`	hora del reloj	sin fecha

Lógica

Tipo	Notas
`boolean`	Casilla de verificación
`toggle`	Igual que boolean, con interfaz de interruptor

Selección

Tipo	Notas
`select`	Opción única — opciones declaradas en línea o referenciadas desde una lista de selección
`multiselect`	Varias opciones, almacenadas como un arreglo
`radio`	Alias de interfaz para `select` con renderizado de botones de opción
`checkboxes`	Alias de interfaz para `multiselect` con renderizado de casillas de verificación

Estructura de las opciones:

options: [
  { value: 'low',    label: 'Low' },
  { value: 'high',   label: 'High',   color: '#e02' },
  { value: 'urgent', label: 'Urgent', color: '#c00' }
]

Relaciones

Tipo	Cardinalidad	Semántica
`lookup`	muchos a uno	Referencia laxa; eliminar el padre no elimina el hijo de forma predeterminada
`master_detail`	muchos a uno, en cascada	El hijo no puede existir sin el padre; los permisos se heredan del padre
`tree`	autorreferencia	Jerárquico (parent_id en el mismo objeto)

Opciones comunes:

{
  type: 'lookup',
  reference: 'account',                       // target object name
  lookupFilters: [                            // narrow the lookup picker
    { field: 'status', operator: 'eq', value: 'active' }
  ],
  deleteBehavior: 'set_null'                  // 'set_null' | 'cascade' | 'restrict'
}

Calculados

Tipo	Qué hace	Opción clave
`formula`	Valor derivado, evaluado al leer o al recalcular	`expression: F\`record.qty * record.unit_price`` — consulta CEL
`summary`	Acumulación sobre una relación hija	`summaryOperations: { object, field, function, filter? }` (`count` \| `sum` \| `avg` \| `min` \| `max`; el `filter` opcional — una condición `where` de consulta, p. ej. `{ status: 'received' }` — agrega solo las filas hijas coincidentes, 16.0+)
`autonumber`	Número de visualización autoincremental	`format` (p. ej. `TKT-{0000}`), `startAt`

Ejemplo de fórmula:

{
  name: 'profit_margin',
  type: 'formula',
  expression: F`(record.revenue - record.cost) / record.revenue * 100`
}

Multimedia

Tipo	Para qué usarlo	Opción clave
`image`	adjuntos de imagen	`multiple` / `accept` / `maxSize` (ver abajo)
`file`	cualquier archivo	igual
`avatar`	fotos de perfil	recorte cuadrado, valores predeterminados sensatos
`video`	subidas de video	captura de duración + miniatura
`audio`	audio	vista previa de forma de onda

{
  type: 'file',
  multiple: true,                             // store an array of attachments
  accept: ['image/png', 'image/jpeg'],        // MIME types / extensions
  maxSize: 10_000_000                         // bytes
}

Estructurados

Tipo	Almacena	Notas
`json`	JSON arbitrario	Almacenado como JSONB en Postgres
`composite`	subregistro con campos nombrados	Estructura en línea, no una tabla separada
`repeater`	arreglo de valores compuestos	Uno a muchos sin un objeto hijo

Interfaz mejorada

Tipo	Notas
`location`	latitud/longitud + precisión
`address`	calle / ciudad / región / código postal / país
`code`	campo de código fuente — `language`, `theme`, `lineNumbers`
`color`	`colorFormat: 'hex' \| 'rgb' \| 'rgba' \| 'hsl'`, `presetColors[]`
`rating`	1–N estrellas — `max`, `icon`
`slider`	número acotado con interfaz de control deslizante
`signature`	firma dibujada, almacenada como imagen
`qrcode`	renderiza el valor como un código QR o de barras (EAN / UPC / Code128)
`progress`	porcentaje derivado renderizado como una barra
`tags`	arreglo de etiquetas de formato libre con autocompletado
`vector`	columna de embedding — `dimensions` plano (p. ej. `1536` para embeddings de OpenAI); el `vectorConfig` anidado (`distanceMetric`/`indexed`/`indexType`) se eliminó en 16.0

Campos del sistema (inyectados automáticamente en cada objeto)

Campo	Tipo	Notas
`id`	text (ULID)	clave primaria
`created_at`	datetime	hora de inserción UTC
`updated_at`	datetime	hora de última escritura UTC
`created_by`	lookup → `user`	quién insertó
`updated_by`	lookup → `user`	quién escribió por última vez
`version`	integer	token de concurrencia optimista

No declaras estos campos — desactívalos por objeto con ObjectSpec.systemFields: false (rara vez es buena idea).

Cómo fluyen los campos a través de la pila

*.object.ts (field spec)
   │
   ├─► Postgres / MySQL / SQLite column + index + constraint
   ├─► REST: validated on POST/PATCH, exposed on GET
   ├─► Console: form widget + list column
   ├─► AI Builder: tool argument schema (so the AI knows what to ask)
   └─► Audit: change-tracked if `trackHistory: true`

Consulta también

Build → Modelo de datos — composición de campos en objetos
CEL — expression, conditionalRequired, validaciones
ObjectQL — consulta de estos campos
REST API — endpoints que los producen / consumen
@objectstack/spec/data/field.zod.ts — esquema autoritativo

On this page