Ir al contenido

Campos

Un campo declara tres cosas a la vez: la columna de D1 —o, en un global, su clave en KV—, la validación que se aplica al escribir, y el componente que lo edita en el administrador. Los declaras una vez y las tres salen solas.

type Columna en D1 Tipo en TypeScript
text text('name') string
textarea text('name') string
number real('name'), o integer con integer: true number
checkbox integer('name', { mode: 'boolean' }) boolean
date integer('name', { mode: 'timestamp_ms' }) Date
select text('name') unión de sus value
radio text('name') unión de sus value
email text('name') string
code text('name') string
json text('name', { mode: 'json' }) unknown
richText text('name', { mode: 'json' }) unknown
relationship text('name') + clave foránea + índice string | Doc
upload text('name') + clave foránea + índice string | Doc
array ninguna: una tabla hija, <colección>_<campo> un array de filas, con id
blocks ninguna: una tabla hija por bloque, <colección>_<campo>_<slug> un array de filas, unión por blockType

textarea genera exactamente la misma columna que text; lo único que cambia es el componente del administrador. Lo mismo vale para radio, que es un select con otro control, y para email y code, que son un text con su regla (el correo) o su editor (el código): los tres son una columna text a secas, así que añadirlos a una colección existente, o cambiar un text por un email, no genera ninguna migración.

array y blocks son listas de filas y no tienen columna en la tabla del documento: sus filas viven en tablas hijas, que se explican en Schema y migraciones. Lo que todavía no hacen se explica más abajo.

text, number y select admiten además hasMany: true, que los convierte en una lista de valores sueltos guardada en una tabla hija: ver hasMany. relationship y upload también, y guardan una lista de documentos: ver hasMany de relaciones.

Hay dos tipos más que no son «un valor en una columna»: group agrupa campos bajo un nombre y point guarda una coordenada en dos columnas. Y cuatro contenedores —row, collapsible, tabs y el group sin nombre— que solo colocan campos y no guardan nada.

Todos los tipos aceptan esto:

{
name: 'publishedAt', // nombre de la columna y clave en la API
label: 'Fecha', // por defecto se deriva del name: 'publishedAt' → 'Published At'
required: true, // validación al escribir; la columna no lleva NOT NULL
unique: true, // índice único
index: true, // índice
defaultValue: 'draft', // se aplica en la aplicación, no como DEFAULT de SQL
hooks: { beforeValidate: [trim] }, // los cuatro de un campo: ver más abajo
admin: {
description: 'Texto de ayuda bajo el campo',
readOnly: false,
hidden: false, // fuera del administrador, presente en la API
position: 'sidebar', // 'main' | 'sidebar'
width: 'half', // 'full' | 'half'
},
}

Un campo con unique: true e index: true genera solo el índice único. Un índice único ya sirve para toda lectura que serviría el normal, y tener los dos duplica el coste de escritura por fila a cambio de nada.

Las cinco claves de admin las lee el editor del panel: description se pinta como pista bajo el campo, readOnly lo deshabilita, hidden lo saca del formulario sin sacarlo de la API, position decide en qué columna cae y width si ocupa media anchura (dentro de una row, cuánto de la línea).

hooks admite cuatro claves —beforeValidate, beforeChange, afterChange y afterRead—, cada una con un array de funciones. Un hook de campo recibe value, el valor de su campo, y lo que devuelva pasa a ser ese valor; devolver undefined lo deja como estaba. Un campo no tiene beforeDelete ni afterDelete: lo que se borra es el documento entero.

cms.config.ts
import type { FieldHook } from '@kevolution-co/cms'
const trim: FieldHook<Post> = ({ value }) => (typeof value === 'string' ? value.trim() : value)
// … dentro de `fields`
{ name: 'tagline', type: 'text', hooks: { beforeValidate: [trim] } }

En beforeValidate y no en beforeChange porque lo que devuelve es lo que la validación va a ver: un tagline que solo llevaba espacios se recorta a la cadena vacía y sale como REQUIRED en vez de guardarse en blanco. Recortar en beforeChange también acaba escrito —lo que un hook de campo asigna se revalida antes de tocar la base—, pero entonces la validación ya ha pasado sobre el valor sin recortar. El orden completo y lo que recibe cada fase están en Hooks.

Toda colección lleva estos tres, sin declararlos:

id: text('id').primaryKey(),
createdAt: integer('createdAt', { mode: 'timestamp_ms' }).notNull(),
updatedAt: integer('updatedAt', { mode: 'timestamp_ms' }).notNull(),

El id es un UUID v7: ordenado por tiempo, así que el índice de la clave primaria sirve además como índice de orden de creación. Redefinir cualquiera de los tres en tu config es un error de configuración.

Un global lleva los tres también, y con dos diferencias: su id es el slug —solo hay un documento— y sus dos fechas se tipan Date | null, porque un global existe desde que lo declaras y antes del primer guardado no hay ninguna. En una colección un documento existe cuando se crea, así que ahí las dos son Date a secas.

{ name: 'slug', type: 'text', required: true, unique: true, minLength: 1, maxLength: 200, pattern: '^[a-z0-9-]+$' }

pattern es una expresión regular en forma de cadena. Se compila al arrancar, así que una mal escrita falla al inicio y no a mitad de una escritura.

placeholder es el texto de ejemplo que el panel pinta dentro del input vacío. Es solo una pista: no se guarda ni se valida, y no sustituye a label ni a admin.description (un campo vacío no debe quedarse sin nombre).

{ name: 'slug', type: 'text', placeholder: 'mi-primer-post' }
{ name: 'excerpt', type: 'textarea', rows: 10 }

rows (solo en textarea) es el alto del campo en líneas: un entero entre 1 y 100, y 6 si no lo declaras. El campo no crece con el texto —tiene su propio scroll—, de modo que rows es lo que decide cuánto sitio ocupa en el formulario. Cualquier otro valor (0, 2.5, 'diez') falla al arrancar con INVALID_FIELD_OPTION.

Para el texto largo con formato, usa richText. textarea se queda para el texto largo sin formato y para el markdown que conviertes tú.

{ name: 'readingTime', type: 'number', integer: true, min: 0, max: 120 }

integer: true cambia las dos mitades a la vez: la columna pasa de REAL a INTEGER y la validación deja de aceptar decimales.

step limita los valores a una rejilla: { name: 'rating', type: 'number', min: 1, max: 5, step: 0.5 } acepta 1, 1.5, 2… y rechaza 1.3. Es un número mayor que cero y la rejilla se cuenta desde min (desde 0 si no hay min), que es de donde la cuenta el navegador: con min: 1 y step: 2 valen 1, 3 y 5, y no 2. La regla es una sola y la aplican las dos mitades: el panel avisa al salir del campo y el servidor rechaza la escritura con INVALID_STEP —por la API local y por HTTP igual—, con el mismo mensaje. La comparación tolera el error de redondeo del punto flotante (0.3 es múltiplo de 0.1).

Sin step, el panel acepta cualquier decimal (any), o enteros si el campo es integer.

{ name: 'featured', type: 'checkbox' }

SQLite no tiene booleanos: se guarda como 0 o 1 y vuelve como boolean.

{ name: 'publishedAt', type: 'date', mode: 'datetime' }

Se guarda como epoch en milisegundos y vuelve como Date. mode ('date', 'datetime' o 'month') solo elige el componente del administrador — los tres guardan lo mismo.

Al escribir acepta un Date o una cadena ISO, porque el mismo campo llega de las dos formas según vengas de la API local o de HTTP.

En el administrador, 'datetime' te da calendario y hora y 'date' solo calendario. Eliges en el huso de tu navegador, que el campo rotula, pero lo que se guarda es UTC en los dos casos. Un 'date' es un día del calendario, no un instante: se guarda tal cual, sin convertir, o cambiaría de día para cualquiera al oeste de Greenwich cada vez que abriera y guardara.

Guardar otro campo desde el panel no toca un date que no has editado. El control solo enseña el día (el minuto en 'datetime', el mes en 'month'), pero el valor guardado —la hora, los segundos— se conserva tal cual; solo cambia si lo cambias tú.

Con mode: 'month' el panel pide solo mes y año (<input type="month">) y se guarda el primer día del mes a las 00:00 UTC: marzo de 2026 es 2026-03-01T00:00:00.000Z. Una fecha cualquiera que llegue por la API a un campo month se guarda como venga —el modo no recorta el valor—, y el panel la muestra con su mes.

format es un patrón que decide cómo se ve la fecha en el panel (la vista previa bajo el campo y la celda del listado). No cambia lo que se guarda ni lo que devuelve la API: un campo con format y el mismo campo sin él guardan exactamente el mismo valor. Usa yyyy yy · MMMM (marzo) MMM (mar) MM M · dd d · HH mm; el texto entre comillas simples es literal y se muestra en UTC.

{ name: 'period', type: 'date', mode: 'month', format: "MMMM 'de' yyyy" } // marzo de 2026
{ name: 'status', type: 'select', required: true, options: ['draft', 'published'] }

Las opciones pueden llevar etiqueta:

options: [
{ label: 'Borrador', value: 'draft' },
{ label: 'Publicado', value: 'published' },
]

La columna es un text a secas, sin CHECK: la lista de opciones la hace cumplir la validación en cada escritura, y por eso cambiarla —añadir una opción, quitar otra— no genera migración. El motivo, y lo que cuesta, está en Sin NOT NULL ni CHECK.

En TypeScript sale la unión de los valores, no string:

status: 'draft' | 'published'

Que es lo que hace que el editor te corrija al escribir una plantilla.

Borrar la elección. Un select de una opción lleva un botón «Borrar» en el panel. Al guardar, el campo vacío llega al servidor como ausente y queda en null —el panel y la API leen null—. Si el campo es required el vacío se sigue rechazando (REQUIRED): el botón no es una forma de saltarse la regla, y por eso un select obligatorio no lo enseña. El hasMany no cambia con esto.

{ name: 'tone', type: 'radio', options: ['formal', 'casual'], layout: 'horizontal' }

Lo mismo que un select —misma lista options, con o sin etiqueta, misma columna text, mismo tipo TypeScript (la unión de los valores) y la misma comprobación en cada escritura, por el panel y por la API: un valor fuera de la lista es un 400 con INVALID_OPTION—, pero con todas las opciones a la vista. layout es 'vertical' (por defecto) o 'horizontal', y solo cambia cómo se colocan.

El panel lo pinta como un grupo de radios nativos dentro de un fieldset con su legend, así que las flechas del teclado cambian de opción y un lector de pantalla anuncia el grupo. Un radio opcional lleva el mismo botón «Borrar» que el select. No admite hasMany (INVALID_HAS_MANY): varias opciones a la vista serían casillas, no radios.

{ name: 'contact', type: 'email', placeholder: 'nombre@dominio.com' }

Una cadena que tiene que ser un correo: a@b.co vale, a@b no (el dominio necesita un punto y una terminación de dos letras o más), con un máximo de 254 caracteres. Solo ASCII: un dominio internacionalizado se escribe en punycode (xn--…). Se comprueba en el panel al salir del campo y en el servidor en cada escritura con el mismo código; el rechazo es INVALID_EMAIL. Admite placeholder, required, unique e index como un text, y se filtra como uno.

{ name: 'snippet', type: 'code', language: 'typescript' }

Una cadena de código fuente, guardada tal cual en una columna text. language es dato —'javascript', 'typescript', 'jsx', 'tsx', 'json', 'html', 'css', 'markdown', 'sql', 'yaml', 'xml' o 'python'; sin él es texto plano— y otro valor falla al arrancar con INVALID_FIELD_OPTION. Admite minLength y maxLength.

En el panel se edita con el editor de código, que colorea según ese mismo language. Los saltos de línea de Windows (\r\n) se normalizan a \n al guardar desde el panel, para que el mismo código no cambie de bytes según el sistema de quien lo edita; lo escrito, tabuladores y Unicode incluidos, se guarda y se recarga idéntico.

{ name: 'meta', type: 'json' }

Para estructuras a medida que no son una lista de filas con forma fija (para eso están array y blocks). Entra cualquier cosa serializable y vuelve tal cual, anidamiento incluido. En TypeScript es unknown, así que te toca estrecharlo.

Sin más opciones, el panel solo comprueba que el texto sea JSON al salir del campo y, si no lo es, dice dónde falla (meta no es JSON válido: línea 2, columna 5); un campo vacío se guarda como null. Lo edita el editor de código, con un botón «Formatear» que reindenta con dos espacios. Para exigir una forma, declara un schema:

{
name: 'config',
type: 'json',
schema: {
type: 'object',
required: ['title'],
properties: { title: { type: 'string' }, depth: { type: 'integer', minimum: 0 } },
},
}

El schema es un JSON Schema escrito como dato: un objeto con valores JSON y nunca una función ni una clase, porque viaja al navegador. Se valida con @cfworker/json-schema (sin eval ni new Function, apto para Workers) en los dos lados con el mismo código: el panel avisa al salir del campo y el servidor rechaza la escritura con JSON_SCHEMA. El mensaje dice qué ruta falla (config no cumple su schema en title: ...); el detalle tras los dos puntos es el del validador y está en inglés.

  • El borrador se toma de $schema (draft-04, draft-07, 2019-09 o 2020-12) y es 2020-12 si no lo hay.
  • Solo se admiten $ref locales (#, #/$defs/x) y tienen que apuntar a algo que exista; una referencia a otro documento, una función, una fecha o un ciclo falla al arrancar con INVALID_JSON_SCHEMA.
  • El validador se descarga solo cuando el campo declara un schema: un panel sin ninguno no lo carga.
  • Un campo opcional vacío (null) no se valida contra el schema; solo un valor presente.

code y json se editan con CodeMirror 6: números de línea, sangría, coloreado del language del campo (json usa el de JSON), deshacer y rehacer, y el tema claro u oscuro del panel con sus mismos colores. No tiene animaciones propias (ni parpadeo del cursor), así que prefers-reduced-motion se respeta sin hacer nada. No carga fuentes ni nada de otro dominio, y no usa eval ni new Function.

Se descarga bajo demanda. El editor no va en el JavaScript del panel: se pide al abrir un formulario que tenga un campo code o json, y de los doce lenguajes solo se baja el modo del que el campo usa. Una página sin esos campos —el listado, los ajustes, un documento con otros tipos— no descarga nada de él. Lo que pesa, ya minificado:

Qué se descarga Sin comprimir gzip
Núcleo del editor (una vez, para todos los campos de la página) 294 KB 94 KB
json 29 KB 10 KB
css 54 KB 21 KB
yaml 39 KB 14 KB
xml 41 KB 14 KB
sql 51 KB 19 KB
python 80 KB 31 KB
javascript, typescript, jsx, tsx (comparten el modo) 120 KB 46 KB
html (trae css y javascript, que admite dentro) 175 KB 70 KB
markdown (trae html, por el HTML de sus bloques) 220 KB 85 KB

Cada fila incluye lo que comparte con otros lenguajes; en una página con dos campos de lenguajes distintos, lo común se descarga una sola vez. El panel entero, sin contar esto, pesa lo mismo que antes del editor salvo unos 10 KB (2,7 KB gzip) de los editores de lista.

Sin JavaScript, mientras carga y si no llega. El campo es primero un área de texto monoespaciada, con el mismo name, que viaja en el HTML del servidor y guarda sin JavaScript. Cuando el editor llega ocupa su lugar con lo que se haya escrito ya, y con el foco y el cursor donde estaban si se estaba escribiendo. Si no llega (la red cae, el despliegue cambió los ficheros), el área se queda, con un aviso, y guarda igual: nada se pierde. Y si el modo del lenguaje no llega, el editor sigue siendo un editor de texto plano.

Teclado. Tab escribe un tabulador (con una selección, la sangra) y Mayús+Tab quita una sangría; para no atrapar el foco, Esc y luego Tab salen del editor al siguiente control, y Ctrl+M (Mayús+Alt+M en Mac) deja Tab como salida hasta que se vuelva a pulsar. Lo dice una línea bajo el campo, que el lector de pantalla lee con él.

Accesibilidad. El editor se nombra con la etiqueta del campo, anuncia que es de varias líneas y lleva su error asociado (aria-invalid, aria-describedby); los errores de un json salen en una región role="alert". El anillo de foco es el de los demás campos. Su altura mínima es fija (12 líneas en code, 8 en json), no depende de lo escrito, y crece hasta 32 rem antes de pasar a desplazarse.

Contrato. El editor no cambia lo que se guarda: es el mismo texto que antes. En json, vacío sigue siendo null, el texto roto no se propaga (el panel dice la línea y la columna) y la validación contra el schema es la de antes. Si necesitas otro editor, sustituye el control con admin.fieldComponents.

La línea y la columna son las del carácter donde el texto deja de ser JSON (o el final, si se acaba antes de tiempo). Los motores recientes no dicen la posición en errores como «Unexpected token», así que el panel la busca en el propio texto en lugar de suponer la línea 1.

Si respondes con una Content-Security-Policy estricta, ten en cuenta que CodeMirror añade su hoja de estilos al documento como un elemento <style> al montarse el primer editor (no usa hojas construibles). Una style-src sin 'unsafe-inline' la rechaza y el editor se queda sin sus estilos. Todavía no hay forma de pasarle un nonce: hasta entonces, la política tiene que admitir 'unsafe-inline' en style-src en las páginas con un campo code o json. Las demás páginas del panel no descargan CodeMirror y no se ven afectadas.

{ name: 'author', type: 'relationship', to: 'users', onDelete: 'cascade' }

to es el slug de otra colección. Se comprueba al arrancar: si apuntas a una que no existe, el error te sugiere la más parecida.

onDelete acepta 'setNull' (por defecto), 'cascade' y 'restrict'. El defecto es deliberado — borrar un autor no debería borrar sus posts en silencio; si es lo que quieres, lo pides.

Siempre lleva índice, lo declares o no.

Con hasMany: true apunta a varios documentos, y to puede ser una lista de colecciones (un campo polimórfico): ver hasMany de relaciones.

{ name: 'cover', type: 'upload', to: 'ssd', accept: ['image/*'] }

Como relationship, pero apuntando a una colección que declare upload. El destino habitual es ssd, la biblioteca de medios que el paquete aporta sin que declares nada; una colección upload tuya vale igual. Si apunta a una que no lo declara, falla al arrancar: sería una clave foránea a una tabla sin ficheros.

accept restringe qué fichero puede referenciar este campo: escribir en cover el id de un PDF es un 400 con código INVALID_FILE_TYPE, aunque el PDF esté bien guardado. Se comprueba al escribir el documento, no al subir el fichero — la subida va contra la colección de ficheros y no sabe qué campo acabará usándolo. No cuesta ninguna consulta si el campo no declara accept.

Es una regla distinta del mimeTypes de la colección, y esa va primero. Ver Ficheros.

Con hasMany: true es una galería: una lista de ficheros, y accept se aplica a cada uno (gallery.1). Ver hasMany de relaciones.

Un editor con formato que guarda un árbol de nodos en JSON, no HTML ni markdown. Sin features activa las de contenido —negrita, cursiva, subrayado, tachado, código en línea, títulos, listas, enlaces, citas, bloques de código y líneas horizontales—, y deja fuera las imágenes, que se piden por nombre. Se pinta en el servidor con <RichText>.

La declaración, las features, las imágenes, la migración desde markdown y los límites están en la guía del texto enriquecido. Las opciones (features, uploadTo, maxSize) y los nodos, en la referencia.

text, number y select guardan un valor. Con hasMany: true guardan una lista de valores sueltos: las etiquetas de un artículo, las palabras clave, las puntuaciones de una reseña. Se escribe y se lee como un array del tipo del campo.

cms.config.ts
defineCollection({
slug: 'posts',
fields: [
{ name: 'title', type: 'text', required: true },
{ name: 'tags', type: 'select', hasMany: true, options: ['news', 'tech', 'life'], maxRows: 5 },
{ name: 'keywords', type: 'text', hasMany: true, required: true, maxLength: 40 },
{ name: 'scores', type: 'number', hasMany: true, integer: true, min: 0, max: 10 },
],
})

Las opciones del tipo (options, maxLength, pattern, min, max, integer…) se aplican a cada valor. En TypeScript sale un array, nunca null:

tags: ('news' | 'tech' | 'life')[]
keywords: string[]
scores: number[]

Un campo sin valores se lee [], tanto si nunca se escribió como si se vació.

Un hasMany no tiene columna en la tabla del documento: cada valor es una fila de la tabla hija <colección>_<campo> (posts_tags, posts_keywords…), la misma mecánica que una lista de filas (detalle en Tablas hijas):

Columna Qué guarda
parent El id del documento
id La posición del valor como texto ('0', '1'…): la tabla se reemplaza entera en cada guardado y nada la nombra, así que no hace falta un UUID. La API no lo expone
_order La posición, desde 0
value El valor, con la columna del tipo: text, real (integer con integer: true)

Cuesta lo que cuesta cualquier tabla hija: una sentencia más por campo hasMany en cada lectura y en cada escritura (T + 2 en un find, 3T + 2 en un update, con T las tablas hijas de la colección), sean 3 los valores o 100. No lleva ningún índice sobre value.

Opción Regla
required Al menos un valor: ni el campo ausente en un alta ni [] lo cumplen (REQUIRED)
minRows / maxRows Enteros con 0 ≤ minRows ≤ maxRows ≤ 1000. maxRows vale 100 si no lo declaras, por lo mismo que en una lista de filas. Solo existen con hasMany: true
defaultValue Un array de valores válidos (dentro de los límites) o una función que lo devuelva. Se aplica en un alta cuando el campo no viene, no en un update
hooks, access Los del campo entero: el hook ve el array. Un access.read denegado lo deja fuera de la respuesta, como a cualquier campo
unique, index No: los valores viven en otra tabla y no hay columna a la que aplicarlos (INVALID_HAS_MANY_OPTION)

Tipos. text, number y select (aquí), y relationship y upload (más abajo). Un textarea no (INVALID_HAS_MANY): para varios textos usa un text.

Solo en colecciones. Un global vive en KV, una clave por campo, y no tiene tablas hijas donde guardar los valores: un hasMany en un global es un INVALID_HAS_MANY al arrancar, con el nombre del global y del campo. Para una lista de valores en un global usa un array con un subcampo (listas en un global) o un json.

Dónde. En el primer nivel de la colección, o dentro de un row, collapsible o tabs sin nombre, que no añaden nivel. No dentro de un group (NESTED_LIST) ni como subcampo de un array o blocks (INVALID_ROW_OPTION). Y no puede llamarse rels: <colección>_rels es un nombre que el CMS se reserva (RESERVED_FIELD_NAME; vale también para una lista de filas).

Un hasMany tampoco puede ser el admin.useAsTitle (INVALID_USE_AS_TITLE).

Código Cuándo
INVALID_HAS_MANY hasMany que no es un booleano, en un tipo que no lo admite (textarea, checkbox…) o en un global
INVALID_HAS_MANY_OPTION unique o index con hasMany, o minRows / maxRows sin él
NESTED_LIST Un hasMany dentro de un group
INVALID_ROWS_LIMIT minRows o maxRows que no son enteros, maxRows por encima de 1000, minRows > maxRows, o required con maxRows: 0
INVALID_DEFAULT Un defaultValue que no es un array, que se sale de los límites o que trae un valor no válido
INVALID_ROW_OPTION hasMany en un subcampo de un array o blocks
RESERVED_FIELD_NAME Un hasMany (o una lista) llamado rels

Cada valor se valida con las reglas de su tipo, con su posición en la ruta (tags.1), y todos los problemas salen juntos. La lista como un todo añade REQUIRED, MIN_ROWS y MAX_ROWS (con una lista que se pasa de maxRows no se miran los valores). Cómo se escribe —por reemplazo— y cómo se lee y se filtra está en Leer y escribir contenido.

El panel edita un hasMany de text, number o select como una lista ordenada, no como JSON, y el orden que ves es el que se guarda (con repetidos, vacíos, el 0 y los negativos de un number, y Unicode):

  • text y number: una fila por valor con su input (de texto, con el placeholder y el maxLength del campo; o numérico, con min, max y step), los botones para subirlo, bajarlo y quitarlo, y un asa para arrastrarlo con el puntero (en una pantalla táctil, manteniéndola pulsada). Añadir pone una fila vacía al final y le da el foco.
  • select: fichas, una por valor elegido, con su etiqueta (la de { label, value }) y un botón para quitarla; el botón Añadir abre un buscador con las opciones (con el teclado: ↓; lo ya elegido sale como «Añadido»). Con el foco en el botón, Retroceso quita la última ficha, y Retroceso o Supr sobre una ficha quita esa. Las fichas se arrastran en horizontal.
  • Teclado: Alt+↑ / Alt+↓ (en las fichas, Alt+← / Alt+→) mueven el elemento que tiene el foco, y un aviso aria-live dice dónde queda. Es la vía para quien no usa el puntero; el asa no entra en el Tab.
  • Límites: minRows y maxRows (100 si no lo declaras) se cuentan bajo la lista, y al llegar al máximo Añadir dice por qué no añade. min, max, step, maxLength y las opciones son las del campo, con los mismos mensajes que el servidor: el panel no inventa una regla propia, y el servidor es quien decide al guardar.
  • Errores: el servidor contesta por elemento (scores.1 debe ser un número) y el panel pinta cada mensaje en el elemento al que habla, atado a él y no a su posición: si mueves o quitas otros, el mensaje sigue con el suyo. Una celda de un number vacía o a medio escribir viaja como el texto que es, para que el servidor la señale en su sitio.
  • Un valor que el panel no entiende (un 1 donde va un texto, una opción que ya no existe) se conserva donde estaba y se dice; se puede quitar, y el servidor decide qué hacer con él al guardar. Lo que ya estaba guardado se abre tal cual aunque el editor cambie, y abrir y guardar sin tocar nada no cambia nada.
  • Sin JavaScript el campo guarda lo que traía (el valor viaja en un input oculto), pero la lista no se puede editar: para eso hace falta el panel con JavaScript.

El campo lleva el nombre del campo como etiqueta de un grupo, no de un input. Las listas funcionan igual dentro de los formularios que el panel abre; un hasMany no puede ser un subcampo de una fila (ver arriba), así que no hay una lista dentro de otra. Si el valor del campo no es el JSON de un array (un dato escrito a mano en D1), el panel lo enseña con el control de json para que lo leas y lo arregles en vez de perderlo.

En el listado, un hasMany se resume con sus valores separados por coma y no se ordena.

relationship y upload también admiten hasMany: true. El campo guarda una lista de documentos en el orden en que la escribes: las categorías de un post, una galería de fotos, las páginas relacionadas.

cms.config.ts
defineCollection({
slug: 'posts',
fields: [
{ name: 'title', type: 'text', required: true },
{ name: 'categories', type: 'relationship', to: 'categories', hasMany: true, maxRows: 5 },
{ name: 'pinned', type: 'relationship', to: 'categories', hasMany: true, onDelete: 'restrict' },
{ name: 'related', type: 'relationship', to: ['categories', 'pages'], hasMany: true },
{ name: 'gallery', type: 'upload', to: 'ssd', hasMany: true, accept: ['image/*'] },
],
})

Todo lo de hasMany vale aquí: required, minRows / maxRows (100 por defecto), defaultValue, hooks, access, la lectura con [] y nunca null, la escritura por reemplazo. Lo que cambia es qué es un elemento y qué pasa cuando el documento al que apunta desaparece.

Con una colección en to, un elemento es el id del documento. Con varias (solo en relationship), es el par { relationTo, value }, porque el id solo no dice de qué colección es:

// Escribir: siempre ids
await cms.collections.posts.create(
{
title: 'Hola',
categories: ['c1', 'c2'],
related: [
{ relationTo: 'pages', value: 'p1' },
{ relationTo: 'categories', value: 'c3' },
],
gallery: ['m1', 'm2'],
},
{ overrideAccess: true },
)

Al leer, depth los hidrata igual que a una relación suelta (depth: 1 por defecto): el id se sustituye por el documento, y lo que no resuelve se queda como el id. Los tipos generados lo dicen (aquí categories lleva labels: { singular: 'Category' }; sin labels, el nombre del tipo sale del slug):

categories: (string | Category)[]
related: (
| { relationTo: 'categories'; value: string | Category }
| { relationTo: 'pages'; value: string | Page }
)[]
gallery: (string | Medio)[]

Escribir sigue siendo con ids: WriteData colapsa string | Category a string y deja el par como { relationTo, value: string }.

Una tabla hija por campo, <colección>_<campo> (posts_categories, posts_related, posts_gallery), con una columna por colección destino, <destino>Id. No hay una tabla _rels compartida:

Columna Qué guarda
parent El id del documento
id La posición del elemento como texto ('0', '1'…)
_order La posición, desde 0
categoriesId, pagesId… Una columna nullable por colección destino, con su clave foránea a ella y un índice propio. En una fila va rellena una sola: la de la colección del elemento

Un campo con un destino tiene una columna; uno polimórfico, una por colección (el guion de un slug es un guion bajo: my-notes → my_notesId). La regla de «una columna por fila» la garantiza la validación de escritura, no un CHECK —añadir un destino lo obligaría a recrear la tabla—, y la lectura salta una fila con todas las columnas a NULL.

No hay clave foránea al padre, como en cualquier tabla hija: borrar el documento borra sus filas desde el código. El índice por columna sirve a la guarda del borrado y a los filtros. Cuesta lo que cuesta una tabla hija: una sentencia más por campo en cada lectura y escritura (T + 2 en un find, 3T + 2 en un update).

onDelete Al borrar un documento al que apunta un elemento
'setNull' (por defecto) El elemento sale de la lista. La clave foránea de la columna es ON DELETE CASCADE sobre la fila del elemento
'restrict' No se borra. RESTRICTED, con el nombre del documento que lo fija y del campo (Posts «Hola» (pinned)). La clave foránea RESTRICT es la red si una referencia se cuela entre la comprobación y el borrado
'cascade' No existe: INVALID_HAS_MANY al arrancar. Borrar el destino tendría que borrar el documento que tiene la lista, y una tabla hija no puede hacerlo

Con 'setNull' el borrado deja un hueco en _order: la lista ['c1', 'c2', 'c3'] queda en las filas 0 y 2. No se renumera. La lectura ordena por _order y no supone que sea contiguo, así que el resto se lee en su orden; la siguiente escritura del campo reemplaza la lista y la numera de nuevo desde 0. El documento que tenía la lista no se toca: su updatedAt no cambia.

required y minRows se comprueban al escribir, no al borrar: quitar un destino puede dejar una lista por debajo del mínimo, que se verá al volver a guardarla. Si un elemento nunca debe desaparecer sin que alguien lo decida, usa 'restrict'.

Un upload se comporta como una relación a un fichero: un fichero que aparece en una galería no se borra (REFERENCED, Posts «Hola» (gallery)), con la guarda de siempre de la biblioteca de medios.

Opción Regla
to Un slug, o (solo relationship con hasMany) una lista de al menos dos slugs distintos. En un upload, una sola colección de ficheros (ssd vale)
onDelete 'setNull' o 'restrict', solo en relationship
accept Solo upload: se comprueba por elemento, y el error lleva su posición (INVALID_FILE_TYPE en gallery.1)
required, minRows, maxRows, defaultValue, hooks, access Los de hasMany
unique, index No (INVALID_HAS_MANY_OPTION)

Siguen valiendo las limitaciones de hasMany: solo en colecciones (un global no admite hasMany, INVALID_HAS_MANY), solo en el primer nivel, no como subcampo de un array, no llamado rels, y no como admin.useAsTitle.

Los de hasMany, más estos:

Código Cuándo
INVALID_HAS_MANY onDelete: 'cascade' (u otro valor que no sea setNull o restrict) en un hasMany de relaciones, o un upload con una lista de colecciones
INVALID_RELATIONSHIP Un to que es una lista con una sola colección, con repetidas o que no son textos; una lista en to sin hasMany; una colección que no existe
INVALID_UPLOAD_TARGET Un upload a una colección que no guarda ficheros, o con una lista en to sin hasMany

Cada elemento se valida con su ruta (categories.1, related.2.relationTo) y todos los problemas salen juntos. Los que añade una relación:

Código Ruta Cuándo
INVALID_RELATION categories.1 El documento al que apunta el elemento no existe
INVALID_TYPE related.0 Un elemento que no es un id (o, en un polimórfico, que no es { relationTo, value })
INVALID_OPTION related.0.relationTo Una colección que el campo no admite
UNRECOGNIZED_KEYS, MIN_LENGTH related.0, related.0.value Un par con claves de más, o con el value vacío
INVALID_FILE_TYPE gallery.1 Un fichero que el accept del campo no admite
RESTRICTED — Borrar algo que un hasMany con onDelete: 'restrict' fija

Un INVALID_RELATION se diagnostica solo cuando la escritura falla: el camino que funciona no paga ninguna consulta de más. Y la escritura es un solo batch: si falla un elemento, ni el documento ni ninguna de sus listas cambian.

Cómo se lee con depth y cómo se filtra (related.pages, related.relationTo) está en Leer y escribir contenido. Añadir un destino a un campo ya migrado es aditivo; quitarlo o convertir el campo no: ver Schema y migraciones.

El panel edita un hasMany de relaciones como una lista ordenada de documentos, no como JSON: cada elemento es una fila con su título (con su nombre y su tamaño, en una galería) y los botones para subirlo, bajarlo y quitarlo, y debajo está Añadir, con un buscador en la colección destino (o la biblioteca y una zona donde soltar ficheros, en un upload). Si el campo tiene varios destinos, eliges primero la colección y cada fila lleva el nombre de la suya. El orden de la lista es el que se guarda. Lo demás —el teclado, los límites, lo que ya no se puede leer— está en Administrador.

En el listado se resume con los ids separados por coma (pages/p1 en un polimórfico) y no se ordena. El filtro de la barra ofrece es, es alguno de y tiene valor para un destino; para un polimórfico solo tiene valor, porque un id necesita la colección y se filtra por related.pages en la API.

Para montar una página con ellos de principio a fin —declararlos, editarlos en el panel, pintarlos en Astro con un switch por blockType y pasar un json que ya tenías— está la guía Construir páginas con blocks.

Una lista no tiene valor ni columna propios: cada fila es una fila de una tabla hija, con su id y su posición. Por eso una lista no lleva required, unique ni index (INVALID_LIST_OPTION): para exigir filas usa minRows, y el índice, si hace falta, va en el subcampo.

Filas que tienen todas la misma forma: los enlaces de un menú, las preguntas de unas FAQ.

cms.config.ts
{
name: 'links',
type: 'array',
minRows: 1,
maxRows: 20,
labels: { singular: 'Enlace', plural: 'Enlaces' },
admin: { rowLabel: 'label', initCollapsed: true },
fields: [
{ name: 'label', type: 'text', required: true },
{ name: 'url', type: 'text', required: true },
{ name: 'kind', type: 'select', options: ['internal', 'external'] },
],
}

Filas de distinta forma, elegidas de un catálogo: el constructor de páginas. Cada bloque tiene su slug, que es el blockType de sus filas y el final del nombre de su tabla.

cms.config.ts
{
name: 'sections',
type: 'blocks',
blocks: [
{
slug: 'hero',
admin: { description: 'Cabecera con título e imagen' },
fields: [{ name: 'title', type: 'text', required: true }, { name: 'image', type: 'upload', to: 'ssd' }],
},
{ slug: 'quote', label: 'Cita', fields: [{ name: 'text', type: 'textarea', required: true }] },
],
}

En el panel, label es lo que dice la pill de cada fila y el catálogo (sin él, el slug en palabras: hero es «Hero», call-to-action es «Call To Action») y admin.description la línea de ayuda del catálogo.

Opción Regla
minRows / maxRows Enteros con 0 ≤ minRows ≤ maxRows ≤ 1000. maxRows vale 100 si no lo declaras. D1 cuenta cada DELETE y cada índice como una escritura, y reemplazar más filas que eso en cada guardado agota la cuota del plan Free
fields / blocks[].fields Entre 1 y 97 subcampos (D1 admite 100 columnas por tabla, y la tabla hija gasta tres)
defaultValue Un array de filas dentro de los límites, o una función que lo devuelva. El defaultValue de un subcampo tiene que ser un valor, no una función (INVALID_ROW_OPTION): la validación lo da por presente y la escritura de filas lo pondrá en las que no traigan el campo
labels, admin.initCollapsed, admin.rowLabel Para el panel. rowLabel nombra el subcampo —text, textarea, select, radio, email o number— que titula cada fila
hooks, access Los de la lista entera: ve el array. Un subcampo no tiene ni hooks ni access ni unique

Qué cabe en una fila. Los trece tipos de un valor y una columna: text, textarea, number, checkbox, date, select, radio, email, code, json, richText, relationship y upload; con las mismas opciones que en el primer nivel (placeholder, rows, step, layout, format, language, schema), validadas con el mismo código y con la ruta de la celda (links.0.contact). No caben group, point ni los contenedores de maquetación (INVALID_ROW_FIELD): una fila es una fila de SQL y un grupo o un punto la partirían en columnas con prefijo. Tampoco cabe otra lista (NESTED_LIST), ni dentro de un group ni de una pestaña con nombre: una lista va en el primer nivel de la colección, o dentro de un row, un collapsible o unas tabs sin nombre, que no añaden nivel.

Nombres. Un subcampo sigue las reglas de cualquier campo y no puede llamarse id, parent, _order ni blockType, que son las columnas de la tabla hija y el discriminador de un bloque (sin distinguir mayúsculas, porque SQLite tampoco). Dos bloques no pueden compartir slug (DUPLICATE_BLOCK), y un blocks necesita al menos uno (EMPTY_BLOCKS).

Las tablas no pueden chocar. Una lista llama a su tabla <colección>_<campo> (y _<slug> en un bloque), y esa tabla no puede ser la de otra colección, la de otra lista, la de una tabla del paquete como users, ni dejar dos índices con el mismo nombre. Se detecta al validar el config, con las dos partes del choque (TABLE_COLLISION): una colección posts con una lista links y otra llamada posts_links dan la misma tabla.

Código Cuándo
NESTED_LIST Una lista dentro de un group, de unas tabs con nombre o de otra lista
INVALID_LIST_OPTION required, unique o index en una lista
INVALID_ROWS_LIMIT minRows o maxRows que no son enteros, maxRows por encima de 1000 o minRows > maxRows
EMPTY_BLOCKS Un blocks sin bloques
INVALID_BLOCK_SLUG Un slug que no es un nombre válido
DUPLICATE_BLOCK Dos bloques con el mismo slug
EMPTY_FIELDS Una fila sin subcampos
TOO_MANY_FIELDS Más de 97 subcampos
INVALID_ROW_FIELD Un group, point, contenedor o tipo desconocido dentro de una fila
INVALID_ROW_OPTION En un subcampo: unique, hooks, access, admin.position, un defaultValue que es una función u onDelete: 'cascade'
INVALID_ROW_LABEL Un admin.rowLabel que no nombra un subcampo de texto, número, select, radio o email
INVALID_DEFAULT Un defaultValue que no es una lista de filas válida
TABLE_COLLISION Dos tablas o dos índices con el mismo nombre

Los nombres de subcampo repetidos, no válidos o reservados salen con los códigos de siempre (DUPLICATE_FIELD, INVALID_FIELD_NAME, RESERVED_FIELD_NAME). Una lista tampoco puede ser el admin.useAsTitle (INVALID_USE_AS_TITLE), y no aparece en las columnas por defecto del listado.

Cada fila se valida contra sus subcampos, con la ruta de la celda (links.0.url), y todos los problemas salen juntos: si fallan una celda de la fila 0, una clave de la fila 1 y el tipo de la fila 2, es un solo 400 con los tres.

{
"error": "VALIDATION_ERROR",
"message": "El documento no es válido",
"issues": [
{ "path": "links.0.url", "code": "REQUIRED", "message": "links.0.url es obligatorio" },
{ "path": "links.1.foo", "code": "UNKNOWN_FIELD", "message": "…" },
{ "path": "links.2", "code": "INVALID_TYPE", "message": "…" }
]
}
Código Cuándo
INVALID_TYPE La lista no es un array (ni siquiera null: una lista vacía es []), o una fila no es un objeto
MIN_ROWS / MAX_ROWS Menos de minRows o más de maxRows filas. Con una lista que se pasa de maxRows no se miran las filas: no merece mil avisos
UNKNOWN_BLOCK En blocks, un blockType ausente o fuera del catálogo (sections.0.blockType)
INVALID_ROW_ID Un id de fila que no es un texto de 1 a 64 caracteres con letras, números, _ o -
DUPLICATE_ROW_ID Dos filas con el mismo id (una sola vez por id, y en blocks cuenta entre todos los bloques)
LIST_TOO_LARGE Una tabla hija de la lista pesa más de 2 000 000 bytes de JSON UTF-8. Se mide en bytes y no en caracteres, y en blocks por bloque

Reglas que conviene saber:

  • La lista se valida entera aunque sea una actualización parcial: una fila presente es una fila completa. Una lista que no viene en un update no se toca.
  • En un create sin la lista, minRows ≥ 1 da MIN_ROWS, salvo que haya un defaultValue, que cuenta como las filas presentes.
  • El id de una fila es opcional: si falta, el servidor le asigna un UUID v7. Si lo traes, que sea único en la lista, porque es la clave de la fila.
  • blockType no es un subcampo: en blocks identifica el bloque, y en un array una clave blockType es UNKNOWN_FIELD.
  • Los 2 000 000 bytes salen del tope de D1 para un parámetro de texto. El cálculo se hace sobre las filas tal como las tiene la API, así que se queda corto con los json y los richText (que se serializan antes de enviarse y se escapan dos veces): el escritor lo vuelve a comprobar sobre el parámetro real.

Una lista se escribe por reemplazo, en la misma llamada a D1 que el documento:

await cms.collections.posts.update(
post.id,
{ links: [{ id: post.links[1].id, label: 'Docs', url: '/docs' }, { label: 'Nueva', url: '/n' }] },
{ overrideAccess: true },
)
// links queda con exactamente esas dos filas, en ese orden
  • Una lista que llega reemplaza sus filas. links: [] las borra todas; una lista que no viene en el update no se toca; links: null es INVALID_TYPE (una lista es un array siempre, y vaciarla es []). No hay parches por fila ni $push: para cambiar una fila se manda la lista entera.
  • Los ids de las filas se conservan. Una fila con id lo mantiene, y a las que no traen se les asigna un UUID v7. El id es único dentro del documento —la clave de la tabla hija es (parent, id)—: dos documentos pueden tener cada uno una fila id: 'a', y mandar el id de una fila de otro documento no da acceso a ella.
  • Los defaultValue de los subcampos se aplican fila a fila, también en un update: con el reemplazo, cada fila que llega es un alta.
  • Atómico. create es un solo batch (el documento y una sentencia por cada tabla hija con filas), update otro (3T + 2 sentencias, con T el número de tablas hijas) y delete otro (2T + 2). Las sentencias son las mismas para 10 filas que para 1000: las filas viajan como un parámetro JSON por tabla. Si una fila falla —un upload que no existe, por ejemplo— no se escribe nada: ni el resto de las filas, ni el título que viajaba en el mismo update.
  • Qué issue sale. Una fila con una clave foránea rota es INVALID_RELATION sobre la lista (links), no sobre la celda: D1 no dice qué fila ni qué columna. Si a la vez falla un campo de primer nivel y una fila, salen los dos issues (author y links). La validación de las filas (links.0.url) sigue dando la ruta de cada celda.
  • ifMatch / If-Match protege también las filas. Con un updatedAt que ya no coincide es un 412, y un id que no existe un 404, y en ninguno de los dos se toca ninguna tabla hija. Sin ifMatch, dos PATCH sobre la misma lista son last-write-wins sobre toda la lista; el panel no manda If-Match.
  • updatedAt cambia en cada guardado, también cuando solo cambian filas.
  • El borrado. delete borra las filas de todas las tablas hijas en el mismo batch. Y un fichero al que apunta una fila no se borra: REFERENCED nombra el documento y el campo (links.icon; sections.hero.image en un bloque). El accept de un upload dentro de una fila se comprueba como en primer nivel.
  • El tamaño. Cada tabla hija viaja en un parámetro de como mucho 2 000 000 bytes (LIST_TOO_LARGE), y se mide sobre lo que de verdad se envía, con los json y los richText ya serializados.

Los hooks ven las listas enteras: el beforeChange de la colección y el de la lista reciben el array, y el afterChange el documento con las filas ya escritas y sus id. Con hooks, originalDoc y previousDoc del update traen las filas de antes.

Un global vive en KV y no tiene tablas hijas: su lista es un array JSON bajo la clave del campo (global:site:nav), sin tabla ni migración. Valen la misma validación y los mismos códigos de arriba, minRows y maxRows, los id y los defaultValue por fila, y el mismo tope de 2 000 000 bytes; solo cambia dónde se guarda.

await cms.globals.site.update(
{ nav: [{ label: 'Docs', href: '/docs' }, { label: 'Blog', href: '/blog' }] },
{ overrideAccess: true },
)
const { nav } = await cms.globals.site.get()
// [{ id: '0199…', label: 'Docs', href: '/docs', … }, { id: '0199…', label: 'Blog', … }]
  • Se escribe entera. Una lista que llega reemplaza la de KV; una que no viene no se toca, y [] la vacía. Cada lista es su propia clave: guardar nav no reescribe sections. Pero KV no tiene escrituras condicionales, así que no hay ifMatch y dos guardados a la vez de la misma lista son last-write-wins sobre toda ella (gana una, entera: nunca una mezcla de filas de las dos).
  • Los id se conservan igual: el que traes, o un UUID v7 para las filas que no lo traen. Una lista guardada antes de que los globals asignaran ids (el [{ href, label }] de un nav guardado como json) se lee igual: cada fila sin id recibe su posición ("0", "1"), la misma en cada lectura, y el siguiente guardado de esa lista lo persiste. Si esa posición ya es el id de otra fila, se le añade _ hasta que quede libre.
  • Las fechas de las filas vuelven como Date, como en una colección. Una fecha ilegible cuesta solo esa celda (se avisa en la consola). Un valor que no es un array de objetos —un texto, un número, una fila que no es un objeto— se lee como si la lista no existiera: [], o su defaultValue, y se avisa nombrando la clave. El siguiente guardado de esa lista lo sobrescribe; como el panel manda todas, cualquier guardado desde el panel lo repara.
  • La lectura completa y no descarta. Una clave que el config ya no declara en una fila, o una fila de un bloque que ya no existe, se lee tal cual. Como update() valida el documento fundido entero —también las listas que no tocas—, guardar el global falla con UNKNOWN_FIELD o UNKNOWN_BLOCK y la ruta de la fila (sections.1.blockType) hasta que la quites de la lista desde el panel. Lo mismo pasa si el config baja maxRows por debajo de las filas guardadas.
  • depth entra en las filas con las reglas del primer nivel: se vuelve a autorizar el destino con el actor, publicOnly solo hidrata hacia colecciones públicas, y una fila de una carpeta reservada de la biblioteca se queda como id. El accept de un upload dentro de una fila se comprueba, y un fichero al que apunta una fila de un global no se borra: REFERENCED dice Sitio (nav.icon) (Sitio (sections.hero.image) en un bloque).
  • Hooks y access. beforeChange y afterChange del global y de la lista ven el array entero, y originalDoc y previousDoc traen la lista de antes con sus id. El access de una lista decide quién la lee y quién la escribe, como el de cualquier campo.
  • select funciona como en una colección: select: ['nav'] la trae entera y select: ['nav.label'] es un QueryError (un 400 por REST).
  • El tamaño. Los 2 000 000 bytes se miden sobre el JSON de las filas, por tipo de bloque en un blocks. Una lista es una clave de KV, que admite 25 MiB, y los topes de cada tipo de bloque se suman en ella: con catorce tipos de bloque llenos ya no cabe, y es LIST_TOO_LARGE sobre la lista, antes de escribir nada.

Una lista no es filtrable ni ordenable, ni tampoco sus subcampos: where y sort con links o links.label, y select con un subcampo (links.label), son un QueryError (un 400 por REST) que dice que es una lista y cómo se lee. El nombre de la lista sí entra en select: select: ['links'] la devuelve entera, y sin select vienen todas (ver Leer listas). En el administrador, su columna del listado no se ordena y su filtro no ofrece operadores.

Un array y un blocks se editan fila a fila. En el listado, una lista se resume como «3 elementos», y las tablas hijas de una lista solo se leen para el listado si la lista es una de sus columnas.

Cada fila es un bloque plegable, con su cabecera y sus subcampos. Lo que sigue vale para las dos listas; lo propio de blocks (el catálogo, el tipo de cada fila) va al final de esta sección:

  • La cabecera lleva el número de la fila, su título y, si algo falla, «1 error» o «N errores». El título es el valor del subcampo que nombra admin.rowLabel (un select enseña la etiqueta de su opción, y uno largo se corta a 60 caracteres) y, sin valor, «Enlace 3»: labels.singular y la posición, o «Fila 3» si la lista no tiene labels. En un blocks es la etiqueta del bloque y la posición: «Portada 2».
  • Plegar. admin.initCollapsed pliega todas las filas al abrir el documento, salvo las que traen un error: una fila con error siempre nace desplegada. El cuerpo de una fila plegada no se pinta, así que un richText plegado no monta su editor. El plegado no se guarda. La cabecera lleva aria-expanded y aria-controls.
  • Añadir. «Añadir enlace» (con labels.singular) crea una fila con su id y con el defaultValue estático de cada subcampo: uno que sea una función no llega al navegador, y su celda queda vacía. El foco va al primer subcampo que se puede editar.
  • Duplicar, mover y eliminar están en el menú de la fila (⋯): Subir, Bajar, Duplicar y Eliminar (un blocks añade Insertar encima e Insertar debajo). Desde la cabecera, Alt+↑ y Alt+↓ suben y bajan la fila, y el asa de su cabecera la arrastra con el puntero (en una pantalla táctil, tras mantenerla pulsada 200 ms): una línea marca dónde caería. Una copia lleva un id nuevo, y mover una fila a donde ya estaba, con el menú, el teclado o el puntero, no ensucia el formulario. Arrastrar es solo una comodidad del puntero: el menú y el teclado hacen lo mismo y son la vía para un lector de pantalla.
  • Los errores del servidor van con su fila. Si un guardado se rechaza, el mensaje de una celda sale en la fila que falló y sigue con ella aunque la muevas, la dupliques o elimines otra; su texto lleva la posición que la fila ocupa ahora.
  • El foco y el lector de pantalla. Al mover o duplicar, el foco queda en la cabecera de la fila; al eliminar, en la de la siguiente, o en el botón de añadir si no queda ninguna. «Quitar lo que no se declara» lleva el foco a la primera fila: el botón que pulsaste desaparece con el aviso. Cada acción se anuncia en una región aria-live: «Fila 2 movida a la posición 3.».
  • maxRows y minRows. Al llegar a maxRows (100 si no lo declaras), «Añadir» y «Duplicar» se deshabilitan y el botón dice «Máximo N». Por debajo de minRows el pie avisa «Mínimo N elementos», sin impedir borrar. El resto lo valida el servidor.
  • Solo lectura. Con admin.readOnly, o si quien edita no puede guardar, no hay menú ni botón de añadir y los subcampos se deshabilitan (las filas se siguen pudiendo plegar). Con admin.hidden no se pinta nada.
  • Sin JavaScript el formulario sigue guardando las filas que hay: el servidor pinta el input oculto con el JSON de la lista, y ninguna celda lleva name. El botón de añadir y el menú, en cambio, necesitan JavaScript.

La lista viaja en el formulario como un solo input oculto con el nombre de la lista, cuyo valor es el JSON de sus filas. Cada celda es el texto de su input, no el valor que devuelve la API: el formulario manda texto, y el servidor convierte cada celda como convierte los campos del primer nivel.

Subcampo En el formulario Lo que se guarda
text, textarea, select, radio, email, code, relationship, upload "Docs", "external", "u1" El texto, o null si está vacío ("")
number "3.5" 3.5, o null si está vacío
checkbox "true" o "" true o false
date "2026-03-01", y con mode: 'datetime' "2026-03-01T10:30", en UTC La fecha
json, richText El texto de su JSON Su valor, o null si está vacío
[
{ "id": "0199…", "label": "Docs", "weight": "3.5", "newTab": "true", "validFrom": "2026-03-01" },
{ "label": "Blog", "weight": "", "newTab": "" }
]
  • El id de cada fila se conserva. Abrir un documento y guardarlo sin tocar la lista deja las mismas filas, con los mismos id y en el mismo orden. Una fila sin id, o con "id": "", es nueva y el servidor le da uno (el editor del panel acuña el suyo con crypto.randomUUID(), y el servidor lo conserva); quitar una fila es borrarla.
  • Una celda que falta se completa con su defaultValue; una celda vacía es null. { "label": "Blog" } guarda el defecto de cada subcampo que lo declara, y { "label": "Blog", "weight": "" } guarda weight: null, igual que un campo del primer nivel que se vacía. Un documento nuevo se abre con las filas del defaultValue de la lista, ya con su id y el defecto de cada subcampo.
  • Un valor escrito con su tipo (3.5, true) pasa tal cual, y el validador dice qué le pasa si no vale.
  • Un error trae la ruta de su celda. El servidor responde con la ruta del problema (links.1.url) y el panel se la pasa a los campos. En un array el mensaje sale bajo su subcampo, la fila se despliega, su cabecera cuenta «1 error» y el foco va a esa celda; lo que ningún subcampo pinta (la fila misma, una clave retirada) sale arriba, en la propia fila. Lo que es de la lista entera (MIN_ROWS, DUPLICATE_ROW_ID) tiene la ruta de la lista: sale al pie y el foco va al botón de añadir, o a la primera fila si la lista está llena y el botón, deshabilitado, no puede tomarlo. Un JSON roto dentro de una celda json o richText es INVALID_JSON en la ruta de esa celda.
  • El access es el de la lista. Un subcampo no lleva access (INVALID_ROW_OPTION): la lista que quien edita no puede leer no llega ni a su navegador, y la que puede leer y no escribir se pinta deshabilitada y no se envía.
  • Guardar sin tocar una lista puede normalizar sus celdas. El formulario manda todas las celdas de cada fila: una que no estaba se guarda null, y un checkbox que era null se guarda false. Es lo mismo que ya pasa con un campo del primer nivel, y los id, el orden y el resto de los valores no cambian.
  • Añadir bloque. El botón abre un menú con el catálogo: cada bloque con su label y, debajo, su admin.description si la tiene. Es un menú y nada más —sin buscador, imágenes ni grupos—, porque un catálogo son unidades o decenas de bloques y un menú los lista enteros. Elegir uno añade al final una fila con su id, su blockType y el defaultValue estático de los subcampos de ese bloque, y el foco va al primero que se puede editar. Con labels.singular el botón lleva ese nombre («Añadir sección»); sin él, «Añadir bloque».
  • Insertar encima e Insertar debajo, en el menú de cada fila, abren el mismo catálogo en un submenú y ponen la fila nueva en esa posición. Al llegar a maxRows el botón y las dos entradas se deshabilitan.
  • El tipo es fijo y se ve. Cada cabecera lleva una pill con la etiqueta del bloque y data-block="hero" (el slug) para colorearla por CSS: [data-block="hero"] { … }. No hay control para cambiar el tipo: se elimina la fila y se añade otra. Tampoco hay un título editable por fila (el blockName de Payload): lo hace admin.rowLabel, que es de la lista y titula las filas de los bloques que tienen ese subcampo.
  • Los subcampos son los del bloque, con la ruta de array (sections.0.title) y sin name: una fila de un tipo muestra solo los suyos.
  • Un tipo que el catálogo no tiene (contenido guardado con un config anterior: en un global, porque en una colección la migración borra la tabla del bloque retirado, con confirmación) no se oculta ni se descarta: se pinta como una fila con error, «tipo desconocido», con su blockType por título, plegada aunque el servidor ya la haya rechazado, sin subcampos y con «Duplicar» deshabilitado. Se puede eliminar desde su menú, y «Quitar lo que no se declara» también la quita. Mientras no se elimine, su valor viaja intacto en el formulario, y guardar falla con UNKNOWN_BLOCK en la ruta de esa fila (sections.1.blockType) sin escribir nada.
  • Sin JavaScript el formulario sigue enviando las filas que hay —también la de un tipo desconocido—, pero el catálogo y el menú de cada fila necesitan JavaScript: sin él no se puede añadir ni insertar un bloque.
cms.config.ts
{
type: 'group',
name: 'seo',
fields: [
{ name: 'metaTitle', type: 'text', required: true },
{ name: 'metaDescription', type: 'textarea' },
{ type: 'group', name: 'og', fields: [{ name: 'title', type: 'text' }] },
],
}

Un group con nombre es un objeto en la API y columnas en la propia tabla. No hay una tabla aparte ni una columna JSON: cada subcampo es una columna de la tabla de la colección, con el nombre del grupo como prefijo.

En la API En la tabla
seo.metaTitle seo_metaTitle
seo.metaDescription seo_metaDescription
seo.og.title seo_og_title

Un grupo dentro de un grupo concatena los nombres. El grupo en sí no tiene columna. El código del proyecto no ve nunca el nombre aplanado: los hooks, las funciones de access, los documentos que devuelve la API y lo que hidrata depth son siempre el objeto anidado.

const page = await cms.collections.pages.findByID(id)
page.seo.metaTitle // 'Mi título'
page.seo.og.title // null

En TypeScript un grupo es un objeto que siempre está, nunca | null: un grupo sin valores guardados se lee como un objeto con todos sus subcampos a null.

.cms/types.d.ts
seo: {
metaTitle: string
metaDescription: string | null
og: {
title: string | null
}
}

Un subcampo es un campo. Admite todo lo que admite uno de primer nivel: required, unique, index, defaultValue, hooks, access por campo y los tipos relationship y upload (con su clave foránea, su índice y su depth). Un unique en seo.canonical crea un índice único sobre seo_canonical, y un duplicado es un 400 con UNIQUE en la ruta seo.canonical, no en el nombre de la columna. Lo único que no admite es llamarse id: en los tipos generados un objeto con id pasaría por un documento relacionado.

El grupo en sí no lleva required, unique, index, defaultValue, hooks ni access, porque no guarda nada propio: se declaran en los subcampos, que son los que tienen columna. Declararlos en el grupo es un error de configuración (INVALID_GROUP_OPTION).

Se lee y se escribe por ruta con puntos. where, sort y select usan seo.metaTitle; el nombre de la columna (seo_metaTitle) no es un campo y se rechaza con un QueryError. Un grupo entero no se filtra ni se ordena —no tiene valor propio—, y select: ['seo'] devuelve el grupo completo.

await cms.collections.pages.find({
where: { 'seo.metaTitle': { equals: 'Inicio' } },
sort: '-seo.priority',
select: ['title', 'seo.metaTitle'],
})
GET /api/cms/pages?where[seo.metaTitle][equals]=Inicio&sort=-seo.priority&select=title,seo.metaTitle

Un select por ruta devuelve el grupo podado a lo pedido; los tipos de la API local lo aceptan, pero devuelven el tipo del documento entero, sin refinarlo.

Escribir. En un create, un grupo que falta se valida como {}: sus subcampos required salen como REQUIRED con su ruta (seo.metaTitle). En un update, un grupo se funde subcampo a subcampo: update(id, { seo: { metaDescription: 'x' } }) cambia esa columna y deja las demás como estaban. Para vaciar un grupo, seo: null pone todos sus subcampos a null —y falla si alguno es required—, y un subgrupo igual (seo: { og: null }). Un grupo que no es un objeto es INVALID_TYPE, y un subcampo que no existe, UNKNOWN_FIELD con su ruta (seo.typo).

await cms.collections.pages.update(id, { seo: { metaDescription: 'Otra' } }, { overrideAccess: true })
await cms.collections.pages.update(id, { seo: { og: null } }, { overrideAccess: true })

Un nombre aplanado no puede repetirse. Un campo seo_title y un grupo seo con un subcampo title generan la misma columna: defineConfig lo rechaza con COLUMN_NAME_CONFLICT y el nombre de la columna. La comparación no distingue mayúsculas, porque SQLite tampoco. Vale para colecciones; un global guarda una clave por campo de primer nivel y no aplana.

Un group con nombre se pinta como un fieldset con su legend (su etiqueta, o su nombre en palabras) y, si la tiene, su admin.description como pista. Sus subcampos son los mismos editores que los de primer nivel, y cada input se llama como la ruta del campo: seo.metaTitle, seo.og.title. Por eso un campo metaTitle suelto y el metaTitle del grupo seo no se pisan: el formulario envía metaTitle y seo.metaTitle, dos entradas distintas. Un error de un subcampo sale bajo su input, con el foco en el primero que falla, y un required vacío al crear devuelve lo escrito sin guardar nada.

  • Los defectos de los subcampos (defaultValue) llegan al formulario de alta, como los de un campo suelto.
  • Un group con admin.readOnly deshabilita todo lo de dentro.
  • Lo que quien guarda no puede ver o escribir no se toca. Un subcampo cuyo access.read rechaza al actor no llega al navegador —ni su valor—, y uno cuyo access.update lo rechaza no se envía ni se acepta si alguien lo manda a mano: guardar conserva lo que ya había. Lo mismo vale para un global.
  • Un group entero que el actor no puede ver (ningún subcampo visible) no se pinta.
  • Los subcampos se guardan con el editor de su tipo, igual que en el primer nivel: un checkbox sin valor (NULL) pasa a false, y una date que no editas conserva su valor tal cual, hora incluida.
  • Un grupo sin nombre y sin etiqueta no pinta nada alrededor de sus campos: solo los coloca.
  • La biblioteca de medios no pinta los grupos de una colección con upload: editar el alt de un fichero deja credit.author como estaba. Se editan por la API.

No cabe un array ni un blocks dentro de un grupo (NESTED_LIST): una lista va en el primer nivel de la colección.

{ name: 'location', type: 'point' }

Una coordenada: en la API es [longitud, latitud] —la longitud primero, como GeoJSON— y en la tabla son dos columnas real nulables, location_lng y location_lat. Dentro de un grupo llevan el prefijo (seo_center_lng).

await cms.collections.pages.update(id, { location: [-74.07, 4.71] }, { overrideAccess: true })
await cms.collections.pages.update(id, { location: null }, { overrideAccess: true }) // limpia las dos columnas
  • La longitud va de −180 a 180 y la latitud de −90 a 90; fuera de rango es un 400 sobre el campo. Un par con una sola coordenada, con tres o con texto, también.
  • Admite required, defaultValue (un par, o una función que lo devuelva), hooks y access. No admite unique ni index: no hay índice sobre un punto (INVALID_POINT_OPTION).
  • Un par a medias en la base —una columna rellena y la otra no— se lee como null.
  • En un where solo admite exists. near y within, y los índices espaciales, no existen todavía.
  • En TypeScript es [number, number], y | null si no es required.
  • Un punto no puede ser el admin.useAsTitle de la colección.
  • Por REST solo viaja en JSON: en un envío multipart simple todo valor es texto y un par no cabe.

Son dos entradas numéricas dentro de un fieldset con la etiqueta del campo: Longitud y Latitud, en ese orden (el de [lng, lat]), con paso libre. Se envían como location.0 y location.1, y el servidor las junta en el par. Los rangos no se copian en el navegador: el que rechaza una latitud de 100 es el servidor, y el error sale bajo la entrada que falló (location.1).

  • Con las dos entradas vacías el campo se guarda null (las dos columnas a NULL). Con una sola rellena no es un par: se rechaza, con el error bajo la entrada que falta, y no se guarda la mitad.
  • Un required vacío se muestra bajo el fieldset y el foco va a la longitud.
  • Un defaultValue rellena las dos entradas al crear.
{ type: 'row', fields: [{ name: 'slug', type: 'text' }, { name: 'views', type: 'number' }] }
{ type: 'collapsible', label: 'Avanzado', initCollapsed: true, fields: [{ name: 'subtitle', type: 'text' }] }
{
type: 'tabs',
tabs: [
{ label: 'General', fields: [{ name: 'note', type: 'text' }] },
{ label: 'Redes', name: 'social', fields: [{ name: 'twitter', type: 'text' }] },
],
}

row, collapsible, tabs y un group sin nombre solo deciden cómo se colocan los campos en el panel: no guardan nada, no añaden columnas y no añaden un nivel al documento. Sus campos viven en la colección como si los hubieras declarado a su lado, y todas las reglas —un nombre repetido, uno reservado, el choque de columnas, lo que exige users— los ven así. Aplicado a campos que ya existen, envolverlos en un contenedor no genera ninguna migración.

Una pestaña con name se comporta como un group con ese nombre (social.twitter, columna social_twitter); el name va en la pestaña, no en tabs. Un contenedor solo admite sus propias claves: un name en un row, por ejemplo, sería un grupo que no lo es, y se rechaza (INVALID_LAYOUT_FIELD).

Todos viven dentro de la isla del editor, sin una isla nueva, y ninguno añade una clave al formulario:

  • row pone sus campos lado a lado a partir del ancho sm y los apila por debajo, sin desbordar la página en un móvil. admin.width reparte la línea: 'half' es el 50 % (menos medio hueco, para que dos quepan) y 'full' toda la línea; los campos sin width se reparten el espacio restante a partes iguales. Fuera de una row, admin.width sigue siendo lo de siempre: 'half' ocupa media columna de la rejilla. El tipo de width es 'full' | 'half'; no hay otros porcentajes.
  • tabs pinta una pestaña por entrada. El servidor entrega todos los paneles apilados, cada uno con su título, que es como se ven con JavaScript desactivado (y se guarda igual). Al montarse en el navegador aparece la lista de pestañas y se ocultan las inactivas, sin desmontarlas: sus campos siguen en el formulario y se envían. Se manejan con el teclado: ←/→ cambian de pestaña (dan la vuelta), Inicio y Fin van a los extremos, y Tab desde una pestaña entra en su panel. Si un error cae en una pestaña, esa es la que se abre y se marca («con problemas»), y el foco va a su campo. Una pestaña con name se pinta igual: la diferencia es solo cómo se guarda.
  • collapsible es un <details> nativo, así que abre y cierra con el teclado y sin JavaScript. initCollapsed: true lo deja cerrado al empezar, salvo que un campo de dentro tenga un error: el foco no puede entrar en un plegado cerrado. Plegarlo no saca sus campos del formulario. Lo que la persona pliega o despliega lo lleva el navegador y no se revierte al escribir en otro campo.
  • group sin nombre con label es un fieldset con esa legend; sin ella, solo coloca.

admin.position: 'sidebar' solo se respeta en el primer nivel: un campo con position: 'sidebar' dentro de un group, una row, un collapsible o unas tabs se queda en su contenedor. Un contenedor no tiene position.

Dentro de la fila de un array o un blocks no cabe un group, un point ni un contenedor (INVALID_ROW_FIELD), y dentro de un group o una pestaña con nombre no caben listas (NESTED_LIST): es el comportamiento actual, y los editores no lo cambian.

La regla es una: required: true da un tipo llano, cualquier otra cosa añade | null.

.cms/types.d.ts
export interface Post {
id: string
createdAt: Date
updatedAt: Date
title: string // required: true
slug: string // required: true
excerpt: string | null // sin required
readingTime: number | null
featured: boolean | null
publishedAt: Date | null
status: 'draft' | 'published' // select con required
meta: unknown | null
cover: string | Medio | null // upload → el id o el documento
author: string | User | null // relationship → el id o el documento
}

Un group es siempre el objeto, sin | null, y un point es [number, number] | null. Una lista (array, blocks) es siempre un array, nunca | null, y sus filas se tipan inline, sin interfaz propia:

.cms/types.d.ts
export interface Post {
// …
links: { id: string; label: string; url: string }[]
sections: (
| { id: string; blockType: 'hero'; title: string | null; image: string | Medio | null }
| { id: string; blockType: 'quote'; text: string | null }
)[]
}

Cada fila lleva su id, y las de un blocks su blockType como literal, con lo que estrechar por él da los subcampos de ese bloque. Sus subcampos siguen la regla de los de primer nivel (required es el tipo llano, el resto lleva | null, y una relación o un upload es la unión). Ni parent ni _order salen nunca. Para nombrar una fila, Post['sections'][number]. Al escribir (create, update, un global) la fila no necesita id —el servidor le pone uno—, una relación se escribe como su id y blockType es obligatorio, así que { blockType: 'otro' } no compila.

Una relationship y un upload se tipan como la unión, no solo como el id: depth se resuelve en tiempo de ejecución y por defecto vale 1, así que TypeScript no puede saber cuál de las dos ramas toca y un tipo que dijera solo string mentiría justo en el caso por defecto. En la plantilla lo estrechas antes de pintarlo — ver Relaciones: depth.

Cada tipo trae su propio control en el panel, y varios hacen bastante más que un input: relationship busca en la colección destino, date abre un calendario o un selector de mes, select se vuelve un buscador a partir de diez opciones y se puede borrar, radio pinta todas sus opciones en un grupo accesible, email y number avisan al salir del campo si el valor no cumple su regla, code y json abren un editor de código (json valida al salir del campo y contra su schema, si lo tiene), un hasMany de text, number o select es una lista que se ordena, upload abre tu biblioteca de medios, richText abre un editor con barra de herramientas y atajos, y array y blocks abren sus filas plegables, con menú y teclado (blocks, además, con un catálogo de tipos). group es un fieldset con sus subcampos, point son dos entradas (longitud y latitud) y row, tabs y collapsible colocan los campos lado a lado, en pestañas y en plegados (los detalles). Los mismos controles pintan el valor de un filtro en el listado; un group y un point no son columna, filtro ni orden del listado del panel.

Puedes sustituir el de cualquier tipo por uno tuyo con admin.fieldComponents. Ver El administrador.

El where y el sort sobre las filas son las siguientes entregas del épico #27. Las tablas hijas, su migración, la escritura y la lectura de las filas, el id de las filas de un global, los editores de array y de blocks y el arrastre de filas ya están. Mientras tanto, para buscar por algo que está dentro de una fila, sácalo a un campo del documento. Y si lo que tienes es un json que quieres pasar a una lista, la receta está en Pasar un json que ya tenías.

Ver también Schema y migraciones para lo que ocurre cuando cambias un campo que ya está en producción.