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.
Los quince tipos
Sección titulada «Los quince tipos»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.
Opciones comunes
Sección titulada «Opciones comunes»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.
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.
Campos de sistema
Sección titulada «Campos de sistema»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.
Tipo por tipo
Sección titulada «Tipo por tipo»text y textarea
Sección titulada «text y textarea»{ 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.
checkbox
Sección titulada «checkbox»{ 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-09o2020-12) y es 2020-12 si no lo hay. - Solo se admiten
$reflocales (#,#/$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 conINVALID_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.
El editor de código
Sección titulada «El editor de código»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.
relationship
Sección titulada «relationship»{ 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.
richText
Sección titulada «richText»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.
hasMany: varios valores en un campo
Sección titulada «hasMany: varios valores en un campo»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.
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ó.
Cómo se guarda
Sección titulada «Cómo se guarda»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.
Qué admite
Sección titulada «Qué admite»| 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ódigos de error de la configuración
Sección titulada «Códigos de error de la configuración»| 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 |
Escribir y leer
Sección titulada «Escribir y leer»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.
Las listas en el administrador
Sección titulada «Las listas en el administrador»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):
textynumber: una fila por valor con su input (de texto, con elplaceholdery elmaxLengthdel campo; o numérico, conmin,maxystep), 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,Retrocesoquita la última ficha, yRetrocesooSuprsobre 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 avisoaria-livedice dónde queda. Es la vía para quien no usa el puntero; el asa no entra en elTab. - Límites:
minRowsymaxRows(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,maxLengthy 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 unnumbervací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
1donde 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.
hasMany de relaciones: varios documentos
Sección titulada «hasMany de relaciones: varios documentos»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.
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.
Qué escribes y qué lees
Sección titulada «Qué escribes y qué lees»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 idsawait 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 }.
Cómo se guarda
Sección titulada «Cómo se guarda»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).
Qué pasa al borrar el destino: onDelete
Sección titulada «Qué pasa al borrar el destino: onDelete»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.
Qué admite
Sección titulada «Qué admite»| 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.
Códigos de error de la configuración
Sección titulada «Códigos de error de la configuración»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 |
Errores al escribir
Sección titulada «Errores al escribir»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.
Leer, filtrar y migrar
Sección titulada «Leer, filtrar y migrar»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.
En el administrador
Sección titulada «En el administrador»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.
array y blocks
Sección titulada «array y blocks»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.
{ 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.
{ 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.
Qué admite una lista
Sección titulada «Qué admite una lista»| 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ódigos de error de la configuración
Sección titulada «Códigos de error de la configuración»| 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.
Escribir una lista
Sección titulada «Escribir una lista»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
updateno se toca. - En un
createsin la lista,minRows ≥ 1daMIN_ROWS, salvo que haya undefaultValue, que cuenta como las filas presentes. - El
idde 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. blockTypeno es un subcampo: enblocksidentifica el bloque, y en unarrayuna claveblockTypeesUNKNOWN_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
jsony losrichText(que se serializan antes de enviarse y se escapan dos veces): el escritor lo vuelve a comprobar sobre el parámetro real.
Cómo se guarda una lista
Sección titulada «Cómo se guarda una lista»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 elupdateno se toca;links: nullesINVALID_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
idlo mantiene, y a las que no traen se les asigna un UUID v7. Elides único dentro del documento —la clave de la tabla hija es(parent, id)—: dos documentos pueden tener cada uno una filaid: 'a', y mandar el id de una fila de otro documento no da acceso a ella. - Los
defaultValuede los subcampos se aplican fila a fila, también en unupdate: con el reemplazo, cada fila que llega es un alta. - Atómico.
createes un solobatch(el documento y una sentencia por cada tabla hija con filas),updateotro (3T + 2sentencias, conTel número de tablas hijas) ydeleteotro (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 —unuploadque no existe, por ejemplo— no se escribe nada: ni el resto de las filas, ni el título que viajaba en el mismoupdate. - Qué issue sale. Una fila con una clave foránea rota es
INVALID_RELATIONsobre 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 (authorylinks). La validación de las filas (links.0.url) sigue dando la ruta de cada celda. ifMatch/If-Matchprotege también las filas. Con unupdatedAtque ya no coincide es un412, y un id que no existe un404, y en ninguno de los dos se toca ninguna tabla hija. SinifMatch, dosPATCHsobre la misma lista son last-write-wins sobre toda la lista; el panel no mandaIf-Match.updatedAtcambia en cada guardado, también cuando solo cambian filas.- El borrado.
deleteborra las filas de todas las tablas hijas en el mismobatch. Y un fichero al que apunta una fila no se borra:REFERENCEDnombra el documento y el campo (links.icon;sections.hero.imageen un bloque). Elacceptde unuploaddentro 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 losjsony losrichTextya 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.
Listas en un global
Sección titulada «Listas en un global»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: guardarnavno reescribesections. Pero KV no tiene escrituras condicionales, así que no hayifMatchy 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
idse 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 unnavguardado comojson) se lee igual: cada fila sinidrecibe 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 sudefaultValue, 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 conUNKNOWN_FIELDoUNKNOWN_BLOCKy la ruta de la fila (sections.1.blockType) hasta que la quites de la lista desde el panel. Lo mismo pasa si el config bajamaxRowspor debajo de las filas guardadas. depthentra en las filas con las reglas del primer nivel: se vuelve a autorizar el destino con el actor,publicOnlysolo hidrata hacia colecciones públicas, y una fila de una carpeta reservada de la biblioteca se queda como id. Elacceptde unuploaddentro de una fila se comprueba, y un fichero al que apunta una fila de un global no se borra:REFERENCEDdiceSitio (nav.icon)(Sitio (sections.hero.image)en un bloque).- Hooks y
access.beforeChangeyafterChangedel global y de la lista ven el array entero, yoriginalDocypreviousDoctraen la lista de antes con susid. Elaccessde una lista decide quién la lee y quién la escribe, como el de cualquier campo. selectfunciona como en una colección:select: ['nav']la trae entera yselect: ['nav.label']es unQueryError(un400por 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 esLIST_TOO_LARGEsobre la lista, antes de escribir nada.
Filtrar, ordenar y seleccionar
Sección titulada «Filtrar, ordenar y seleccionar»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.
Editar una lista en el panel
Sección titulada «Editar una lista en el panel»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(unselectenseña la etiqueta de su opción, y uno largo se corta a 60 caracteres) y, sin valor, «Enlace 3»:labels.singulary la posición, o «Fila 3» si la lista no tienelabels. En unblockses la etiqueta del bloque y la posición: «Portada 2». - Plegar.
admin.initCollapsedpliega 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 unrichTextplegado no monta su editor. El plegado no se guarda. La cabecera llevaaria-expandedyaria-controls. - Añadir. «Añadir enlace» (con
labels.singular) crea una fila con suidy con eldefaultValueestá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 (unblocksañade Insertar encima e Insertar debajo). Desde la cabecera,Alt+↑yAlt+↓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 unidnuevo, 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.». maxRowsyminRows. Al llegar amaxRows(100 si no lo declaras), «Añadir» y «Duplicar» se deshabilitan y el botón dice «Máximo N». Por debajo deminRowsel 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). Conadmin.hiddenno 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
idde cada fila se conserva. Abrir un documento y guardarlo sin tocar la lista deja las mismas filas, con los mismosidy en el mismo orden. Una fila sinid, o con"id": "", es nueva y el servidor le da uno (el editor del panel acuña el suyo concrypto.randomUUID(), y el servidor lo conserva); quitar una fila es borrarla. - Una celda que falta se completa con su
defaultValue; una celda vacía esnull.{ "label": "Blog" }guarda el defecto de cada subcampo que lo declara, y{ "label": "Blog", "weight": "" }guardaweight: null, igual que un campo del primer nivel que se vacía. Un documento nuevo se abre con las filas deldefaultValuede la lista, ya con suidy 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 unarrayel 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 celdajsonorichTextesINVALID_JSONen la ruta de esa celda. - El
accesses el de la lista. Un subcampo no llevaaccess(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 uncheckboxque eranullse guardafalse. Es lo mismo que ya pasa con un campo del primer nivel, y losid, el orden y el resto de los valores no cambian.
blocks: el catálogo y el tipo de cada fila
Sección titulada «blocks: el catálogo y el tipo de cada fila»- Añadir bloque. El botón abre un menú con el catálogo: cada bloque con su
labely, debajo, suadmin.descriptionsi 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 suid, sublockTypey eldefaultValueestático de los subcampos de ese bloque, y el foco va al primero que se puede editar. Conlabels.singularel 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
maxRowsel 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"(elslug) 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 (elblockNamede Payload): lo haceadmin.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 sinname: 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
blockTypepor 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 conUNKNOWN_BLOCKen 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.
group, point y los contenedores
Sección titulada «group, point y los contenedores»{ 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 // nullEn 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.
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.metaTitleUn 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 en el panel
Sección titulada «Un group en el panel»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
groupconadmin.readOnlydeshabilita todo lo de dentro. - Lo que quien guarda no puede ver o escribir no se toca. Un subcampo cuyo
access.readrechaza al actor no llega al navegador —ni su valor—, y uno cuyoaccess.updatelo 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
groupentero 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
checkboxsin valor (NULL) pasa afalse, y unadateque 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 elaltde un fichero dejacredit.authorcomo 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
400sobre 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),hooksyaccess. No admiteuniqueniindex: 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
wheresolo admiteexists.nearywithin, y los índices espaciales, no existen todavía. - En TypeScript es
[number, number], y| nullsi no esrequired. - Un punto no puede ser el
admin.useAsTitlede la colección. - Por REST solo viaja en JSON: en un envío multipart simple todo valor es texto y un par no cabe.
Un point en el panel
Sección titulada «Un point en el panel»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 aNULL). 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
requiredvacío se muestra bajo elfieldsety el foco va a la longitud. - Un
defaultValuerellena las dos entradas al crear.
Contenedores de maquetación
Sección titulada «Contenedores de maquetación»{ 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).
Los contenedores en el panel
Sección titulada «Los contenedores en el panel»Todos viven dentro de la isla del editor, sin una isla nueva, y ninguno añade una clave al formulario:
rowpone sus campos lado a lado a partir del anchosmy los apila por debajo, sin desbordar la página en un móvil.admin.widthreparte la línea:'half'es el 50 % (menos medio hueco, para que dos quepan) y'full'toda la línea; los campos sinwidthse reparten el espacio restante a partes iguales. Fuera de unarow,admin.widthsigue siendo lo de siempre:'half'ocupa media columna de la rejilla. El tipo dewidthes'full' | 'half'; no hay otros porcentajes.tabspinta 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 connamese pinta igual: la diferencia es solo cómo se guarda.collapsiblees un<details>nativo, así que abre y cierra con el teclado y sin JavaScript.initCollapsed: truelo 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.groupsin nombre conlabeles unfieldsetcon esalegend; 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.
Nulabilidad
Sección titulada «Nulabilidad»La regla es una: required: true da un tipo llano, cualquier otra cosa añade | null.
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:
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.
En el administrador
Sección titulada «En el administrador»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.
Lo que falta de array y blocks
Sección titulada «Lo que falta de array y blocks»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.