# Schema reference

> Every field type of galerne.config.ts with its options, validation rules, languages, singletons, blocks, the studio structure and the built-in guidelines type.

The content model of a project lives in `galerne.config.ts`, in your repository. `galerne schema deploy` sends it to the project; `galerne schema pull` writes the deployed one back to a file. The studio, the API and agents all validate against it.

```ts
import { defineConfig } from '@galerne/schema'

export default defineConfig({
  languages: ['en', 'fr', 'de'],
  types: { /* document types */ },
  blocks: { /* block types for blocks fields */ },
  structure: [ /* the studio sidebar, optional */ ],
})
```

| Key | Type | What it is |
|---|---|---|
| `languages` | `string[]` | Language codes of the project. The first is the default and the delivery fallback. Defaults to `["en"]`. |
| `types` | `Record<string, DocType>` | Document types. At least one. |
| `blocks` | `Record<string, BlockType>` | Block types used by `blocks` fields. |
| `structure` | `StructureItem[]` | The studio sidebar. Without it, the sidebar lists every type in config order. |

Names of types, blocks and fields start with a letter and use letters, digits and `_`. Language codes look like `en`, `fr` or `pt-BR`.

## Document types

```ts
post: {
  title: 'Post',
  description: 'Articles of the blog',
  preview: { title: 'title', subtitle: 'slug', media: 'cover' },
  fields: { /* … */ },
}
```

| Option | Type | What it does |
|---|---|---|
| `title` | `string` | Name shown in the studio. Defaults to the key. |
| `description` | `string` | Help text in the studio, also given to agents. |
| `fields` | `Record<string, Field>` | The fields. Their order is the order of the editing form. |
| `preview` | `{ title?, subtitle?, media? }` | Field names that document lists show. |
| `singleton` | `boolean` | One document only, such as the homepage or site settings. Its id is the type name. |
| `orderable` | `boolean` | Documents get a manual order in lists (navigation, team members), stored in `_order`. |
| `i18n` | `"doc"` | Document-level translations: one document per language. See [languages](#languages). |

## Options every field takes

| Option | Type | What it does |
|---|---|---|
| `type` | `string` | The field type, below. Required. |
| `title` | `string` | Label in the studio. |
| `description` | `string` | Help text in the studio and in the JSON Schema agents read. |
| `required` | `boolean` | The field needs a value to publish. |
| `requiredIf` | `{ field, equals? }` | Required when a sibling field has a value, or equals the given value. |
| `localized` | `boolean` | One value per language: `{ "en": …, "fr": … }`. Needs two languages or more. |
| `readOnly` | `boolean` | Shown but not editable in the studio. |
| `hidden` | `boolean` | Not shown in the studio. |
| `component` | `string` | Another input in the studio, such as `character-count`. See [custom inputs](/docs/studio.md#custom-inputs). |
| `componentOptions` | object | Options of that input, such as `{ "max": 160 }`. |

## Field types

### string

A single line of text, or a choice from a list.

| Option | Type | What it does |
|---|---|---|
| `options` | `{ value, title? }[]` | Allowed values. The studio shows a select. |
| `min`, `max` | `number` | Length in characters. |
| `regex` | `string` | A regular expression the value must match. |
| `unique` | `boolean` | No other document of the type (and language) may have the same value. |

### text

Several lines of plain text. Options: `min`, `max` (characters), `rows` (height of the input in the studio).

### richText

Formatted text, stored as ProseMirror JSON. The API and MCP accept and return Markdown, and the query API can return HTML.

| Option | Type | What it does |
|---|---|---|
| `nodes` | `string[]` | Allowed nodes: `paragraph`, `heading`, `bulletList`, `orderedList`, `listItem`, `blockquote`, `codeBlock`, `horizontalRule`, `hardBreak`, `image`, `table`. All by default. |
| `marks` | `string[]` | Allowed marks: `bold`, `italic`, `strike`, `code`, `link`, `underline`. All by default. |

In Markdown, link to another document with `[text](doc:<id>)` and embed an image with `![alt](media:<id>)`. Links to documents survive slug changes because they point to the id.

### url

A URL, or a path starting with `/`. Option: `schemes`, the allowed schemes (default `http`, `https`, `mailto`, `tel`).

### email

An email address. No options.

### slug

Lowercase letters, digits and single dashes, such as `hello-world`. Slugs are unique per type and language.

| Option | Type | What it does |
|---|---|---|
| `from` | `string` | A sibling field the studio builds the slug from. |
| `max` | `number` | Maximum length. Default 200. |

### number

Options: `min`, `max`, `integer` (whole numbers only).

### boolean

`true` or `false`. No options.

### date and datetime

`date` takes `YYYY-MM-DD`. `datetime` takes an ISO 8601 date and time, such as `2026-10-16T09:00:00+02:00`. Both take `min` and `max` in the same format.

### color

A hex color: `#RGB`, `#RRGGBB` or `#RRGGBBAA`. No options.

### geopoint

`{ "lat": 48.85, "lng": 2.35, "alt"?: 35 }`. Latitude between -90 and 90, longitude between -180 and 180.

### code

A string, or `{ "code": "…", "language": "ts" }`. Options: `language` (a fixed language) or `languages` (a list to choose from).

### table

`{ "rows": [["Name", "Role"], ["Ada", "Engineer"]] }`: rows of strings. Option: `columns`, the column names the studio shows.

### image

```json
{ "asset": "m_7Qk…", "alt": "Harbour at dawn", "caption": "Douarnenez", "hotspot": { "x": 0.5, "y": 0.4 }, "crop": { "top": 0, "bottom": 0.1, "left": 0, "right": 0 } }
```

| Option | Type | What it does |
|---|---|---|
| `altRequired` | `boolean` | The alt text is required to publish. |
| `fields` | `Record<string, Field>` | Extra fields stored next to the asset, such as `credit`. |

Delivered images also carry `url`, `mimeType`, `size`, `width` and `height`. Upload files with the API or `upload_media`; see [media](/docs/media.md).

### file

`{ "asset": "m_…", "filename"?: "report.pdf" }`. Option: `accept`, a list of allowed MIME types or extensions, used by the studio picker.

### reference

A link to another document: `{ "_ref": "<doc id>" }`.

| Option | Type | What it does |
|---|---|---|
| `to` | `string[]` | Types it may point to. Required. |
| `weak` | `boolean` | The target may be deleted while referenced. Strong references block the delete. |

The query API replaces references with the documents they point to when you pass `expand`.

### object

A group of fields stored as one object: `{ type: 'object', fields: { … } }`. Paths reach inside with dots: `seo.description`.

### list

A list of strings, numbers or references.

| Option | Type | What it does |
|---|---|---|
| `of` | `"string"`, `"number"` or `"reference"` | Type of the items. |
| `to` | `string[]` | For lists of references: the types they may point to. |
| `options` | `{ value, title? }[]` | For lists of strings: allowed values. |
| `min`, `max` | `number` | Number of items. |

### blocks

An ordered list of blocks, each from a block type declared under `blocks`. Use it for page builders.

```ts
blocks: {
  quote: { title: 'Quote', fields: { text: { type: 'text', required: true }, author: { type: 'string' } }, preview: { title: 'text' } },
  callout: { title: 'Callout', fields: { tone: { type: 'string', options: [{ value: 'info' }, { value: 'warning' }] }, body: { type: 'richText' } } },
},
types: {
  page: { fields: { content: { type: 'blocks', of: ['quote', 'callout'], max: 40 } } },
},
```

Each block is stored as `{ "_type": "quote", "_key": "k3f9", … }`. The `_key` is stable: keep it when you edit a block, so history, comments and merges follow the block. Paths address a block by key: `content[k3f9].text`. Options: `of` (block type names, required), `min`, `max`.

## Validation

Every write runs the same validation, in the studio, the API, the CLI and MCP. Errors come back with the field path, the rule and a message:

```json
{ "path": "seo.description", "rule": "max", "message": "at most 160 characters" }
```

| Rule | When |
|---|---|
| `required` | A required field is empty (for localized fields, in the default language) |
| `type` | The value has the wrong shape |
| `min`, `max` | Length, count, value or date out of range |
| `options` | The value is not one of the options |
| `regex`, `slug`, `email`, `url`, `integer`, `range` | The value does not match the format |
| `unique` | Another document of the type already uses this value |
| `unknown` | The field is not in the schema |
| `language` | A localized value uses a language the project does not have |
| `richText` | A node or mark the field does not allow |

Drafts save with `required` and `min` errors, which show as warnings, so people and agents can work in steps. Every other error rejects the write. Publishing needs a document with no errors at all.

Content checks go further than validation: broken links and references, missing alt text, heading order, vague link text, duplicate slugs, missing or outdated translations, and unused media. The `check` tool returns them, and branch reviews list them. The `accessibility_report` tool groups the accessibility rules (missing alt text, heading order, vague link text) per type, for a whole branch.

## Languages

Declare the languages once:

```ts
languages: ['en', 'fr', 'de'],
```

There are two ways to translate, chosen per type. You can mix them in one project.

**Field level**: mark fields `localized: true`. One document holds every language:

```json
{ "title": { "en": "Harbours", "fr": "Ports", "de": "Häfen" } }
```

**Document level**: set `i18n: 'doc'` on the type. Each language is its own document, with `_lang` set and `_translationOf` pointing to the source document. Use it when translations differ in structure or are published on their own schedule.

At delivery, pass `lang` to get one language: localized fields collapse to their value in that language, and document-level types return only documents in that language. Add `fallback: true` to use the default language where a translation is missing. The checks report missing translations, and translations whose source changed after them.

## Singletons

```ts
settings: {
  title: 'Site settings',
  singleton: true,
  fields: { siteName: { type: 'string', required: true }, logo: { type: 'image' } },
},
```

The single document's id is the type name, `settings`. Fetch it with `get_doc` or `query` with `ids: ["settings"]`.

## Studio structure

`structure` orders the studio sidebar with groups, filtered lists, singletons and dividers:

```ts
structure: [
  { singleton: 'settings', title: 'Settings' },
  { divider: true },
  { group: 'Blog', items: [
    { type: 'post', title: 'News', filter: { category: 'news' } },
    { type: 'person', title: 'Authors' },
  ] },
  { type: 'page' },
],
```

## The guidelines type

Every project has a `guidelines` singleton, even when your config does not declare it. It holds how the project writes, and `get_guidelines` serves it to agents.

| Field | Type | What it holds |
|---|---|---|
| `voice` | richText | Voice and tone |
| `audience` | text | Who the content is for |
| `glossary` | table, columns `term`, `use`, `language` | Terms and the wording to use, per language |
| `bannedWords` | list of strings | Words to avoid |
| `examples` | richText | Good examples |
| `rules` | list of strings | House rules |

To shape it yourself, declare a `guidelines` type in your config: yours replaces the built-in one, and `get_guidelines` returns its values.

## System fields

Every delivered document carries `_id`, `_type`, `_rev`, `_createdAt` and `_updatedAt`, plus `_publishedAt` once published. Document-level translations add `_lang` and `_translationOf`, and orderable types add `_order`. You can filter and order on them.

## Changing the schema

`galerne schema diff` lists changes and flags the breaking ones: a removed language, type or field, a changed field type, a field that becomes required or changes between localized and not, and removed options, block types or reference targets. A breaking change only counts when documents of that type exist. Breaking changes need `galerne schema deploy --force`. Content keeps its values; documents that no longer validate show errors in the studio and in `check` until someone fixes them.

Agents can check a change with `propose_schema_change`, which returns the diff against `main` and problems without deploying anything.

## Change the schema on a branch

A schema change usually comes with the site code that uses it, and that code waits for review on a branch. Deploy the change on the same branch:

```bash
galerne schema deploy --branch agent/stack-section
```

Agents call `deploy_schema` with `branch`. The config is stored on the branch, and `main` and the other branches keep the deployed schema. On that branch, writes and validation use the branch's schema, so agents can create documents of the new types there, and `get_schema` with `branch` returns it. Deploying again on the branch replaces it; deploying the same config as `main` removes it.

Reviewers see the schema diff with the branch's changes, in the studio and in `branch_changes`, and `request_review` adds it to the review note.

Promoting the branch deploys its schema on `main` first, in the same transaction as the content, and records it in the schema history with the person who promoted. If `main` deployed a schema in the meantime, both sets of changes merge. When both changed the same part, promotion stops with a `409` that lists the paths; deploy the branch's config again, based on `main`'s current schema, then promote. Breaking changes need `force` on the branch as they do on `main`, and promotion stops when the schema would break content that `main` gained since.

Deploying on a branch needs the same right as deploying on `main`: the admin role and an `admin` token, within the member's allowed branches. Promoting needs the promote right only, since an admin already deployed the schema on the branch.
