docs menu

Schema reference

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 */ ],
})
KeyTypeWhat it is
languagesstring[]Language codes of the project. The first is the default and the delivery fallback. Defaults to ["en"].
typesRecord<string, DocType>Document types. At least one.
blocksRecord<string, BlockType>Block types used by blocks fields.
structureStructureItem[]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: { /* … */ },
}
OptionTypeWhat it does
titlestringName shown in the studio. Defaults to the key.
descriptionstringHelp text in the studio, also given to agents.
fieldsRecord<string, Field>The fields. Their order is the order of the editing form.
preview{ title?, subtitle?, media? }Field names that document lists show.
singletonbooleanOne document only, such as the homepage or site settings. Its id is the type name.
orderablebooleanDocuments get a manual order in lists (navigation, team members), stored in _order.
i18n"doc"Document-level translations: one document per language. See languages.

Options every field takes#

OptionTypeWhat it does
typestringThe field type, below. Required.
titlestringLabel in the studio.
descriptionstringHelp text in the studio and in the JSON Schema agents read.
requiredbooleanThe field needs a value to publish.
requiredIf{ field, equals? }Required when a sibling field has a value, or equals the given value.
localizedbooleanOne value per language: { "en": …, "fr": … }. Needs two languages or more.
readOnlybooleanShown but not editable in the studio.
hiddenbooleanNot shown in the studio.
componentstringAnother input in the studio, such as character-count. See custom inputs.
componentOptionsobjectOptions of that input, such as { "max": 160 }.

Field types#

string#

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

OptionTypeWhat it does
options{ value, title? }[]Allowed values. The studio shows a select.
min, maxnumberLength in characters.
regexstringA regular expression the value must match.
uniquebooleanNo 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.

OptionTypeWhat it does
nodesstring[]Allowed nodes: paragraph, heading, bulletList, orderedList, listItem, blockquote, codeBlock, horizontalRule, hardBreak, image, table. All by default.
marksstring[]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.

OptionTypeWhat it does
fromstringA sibling field the studio builds the slug from.
maxnumberMaximum 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 } }
OptionTypeWhat it does
altRequiredbooleanThe alt text is required to publish.
fieldsRecord<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.

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>" }.

OptionTypeWhat it does
tostring[]Types it may point to. Required.
weakbooleanThe 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.

OptionTypeWhat it does
of"string", "number" or "reference"Type of the items.
tostring[]For lists of references: the types they may point to.
options{ value, title? }[]For lists of strings: allowed values.
min, maxnumberNumber 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" }
RuleWhen
requiredA required field is empty (for localized fields, in the default language)
typeThe value has the wrong shape
min, maxLength, count, value or date out of range
optionsThe value is not one of the options
regex, slug, email, url, integer, rangeThe value does not match the format
uniqueAnother document of the type already uses this value
unknownThe field is not in the schema
languageA localized value uses a language the project does not have
richTextA 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.

FieldTypeWhat it holds
voicerichTextVoice and tone
audiencetextWho the content is for
glossarytable, columns term, use, languageTerms and the wording to use, per language
bannedWordslist of stringsWords to avoid
examplesrichTextGood examples
ruleslist of stringsHouse 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.