Introducción a los schemas de Sanity

Los schemas definen qué contenido pueden editar los clientes desde el Studio. En este boilerplate están organizados en tres capas que se construyen de abajo hacia arriba: objetos reutilizables, secciones de página y documentos raíz.

Estructura de archivos

apps/studio/
├── schemaTypes/
│   └── index.ts          ← Registro central de todos los tipos
└── schemas/
    ├── objects/           ← Tipos de datos reutilizables
    │   └── SEOBase.ts     → type: "seo"
    ├── sections/          ← Bloques visuales de página
    │   └── base.ts        → type: "baseSection"
    ├── helpers/           ← Utilidades compartidas entre documentos
    │   └── sections.ts    → sectionsField
    └── documents/         ← Documentos raíz (una entrada = una página)
        ├── plainPage.ts   → type: "page"
        └── indexPage.ts   → type: "indexPage"

Capa 1 — Objetos

Los archivos en schemas/objects/ definen tipos de datos que no generan entradas propias en el Studio, sino que se incluyen como campos dentro de documentos u otros objetos.

El objeto actualmente registrado es seo (exportado desde SEOBase.ts). Cualquier documento puede añadir un campo type: "seo" para obtener los cuatro campos de SEO completos.

Capa 2 — Secciones

Los archivos en schemas/sections/ definen los bloques visuales que los editores pueden añadir a una página — un hero, un grid de tarjetas, un bloque de preguntas frecuentes, etc.

La sección actualmente registrada es baseSection (exportada desde base.ts). Incluye los campos comunes a la mayoría de bloques: eyebrow, heading, subheading, array de CTAs, imagen con hotspot y variante visual.

Las secciones no se añaden directamente a los documentos. Se centralizan en helpers/sections.ts a través de sectionsField.of, que es el array de tipos disponibles en cualquier campo de secciones. Esto permite agregar una sección nueva en un solo lugar y que esté disponible en todos los documentos automáticamente.

Capa 3 — Documentos

Los archivos en schemas/documents/ definen los documentos raíz. Cada documento se convierte en una entrada en el Studio, normalmente correspondiente a una URL del sitio.

El registro central

Todos los tipos fluyen hacia schemaTypes/index.ts, que los agrupa y los exporta como el array que Sanity consume en sanity.config.ts:

// schemaTypes/index.ts
import {seoBase} from '../schemas/objects/SEOBase'
import {baseSection} from '../schemas/sections/base'
import {pageDocument} from '../schemas/documents/plainPage'
import {indexPageDocument} from '../schemas/documents/indexPage'
 
export const schemaTypes = [
  seoBase,
  baseSection,
  pageDocument,
  indexPageDocument,
]

El orden importa: los tipos objeto y sección deben declararse antes que los documentos que los referencian.

Relación entre capas

schemaTypes/index.ts
  ├── seoBase        → name: "seo"      ← referenciado como type: "seo" en documentos
  ├── baseSection    → name: "baseSection" ← referenciado vía sectionsField.of
  ├── pageDocument   → name: "page"
  └── indexPageDocument → name: "indexPage"

helpers/sections.ts
  └── sectionsField.of = [{type: "baseSection"}]
        ← spreadido en page (campo sections)
        ← usado en indexPage (campos sectionsTop y sectionsBottom)

El nombre de tipo que Sanity usa para resolver referencias es siempre el valor de name: dentro de defineType, no el nombre del export de JavaScript.