Schema as code
Keep your content types and components in your repository and create or change them from a script or CI with the Management API, with a dry run, safe field changes and generated types.
How-to guide11 min read
Editors can build the schema under Schema in CMS Orbit, but many teams prefer to keep it next to the website code: reviewed in pull requests, the same in every space, and changed in the same commit as the components that render it. This guide sets that up with a definition file, a sync script and a CI job. It uses Node 20 or later and no packages.
The command line does all of this for you: cms-orbit schema init writes the schema as typed TypeScript files, and schema validate, schema diff, schema push and schema rollback check, compare, apply and undo it, with a snapshot before every push. This guide shows how it works underneath, for when you want your own script.
Before you start
- A management token (
cms_mt_…) from Organisation › Management tokens, created by someone allowed to change the schema. The token acts as that person. A read-only token is enough for the dry run. - Your organisation id and space id: they are in the CMS address,
/o/{organisationId}/s/{spaceId}/. - Know that the schema belongs to the space, not to an environment. A change reaches Staging and Production at once, so make it safe for the website that is live (see "Change fields safely" below).
What the API offers
/components, GET/content-types/components/{key}, GET/content-types/{key}404/components, POST/content-types409 if the key exists./components/{key}, PATCH/content-types/{key}fields replaces the whole list./components/{key}, DELETE/content-types/{key}All addresses start with https://api.bifrostorbit.com/cms/manage/v1/organisations/{organisationId}/spaces/{spaceId}. Every property and limit is in the Management API reference, and field settings in Field types.
Things to know before you script it:
- Keys are fixed. A component's or content type's
key, and a field'skey, cannot be renamed. fieldsis the whole list. APATCHwithfieldsreplaces every field, so always send all of them, in order.- Slots must say what they accept. A
componentorcomponentsfield needsallowedComponents. - The address prefix is set by update only.
urlPrefixon a content type, such as/journal, can be sent withPATCH, notPOST. It is accepted only while every entry already lives under it, so set it before entries exist. - The schema version moves each time a definition's fields change. Entries keep every value they hold.
1Describe the schema
Make a folder cms/ in your repository with a client, the definitions and the sync script. First the client, which the Import content guide uses too:
const API = process.env.ORBIT_API ?? 'https://api.bifrostorbit.com/cms/manage/v1'const TOKEN = process.env.ORBIT_TOKENconst BASE = `${API}/organisations/${process.env.ORBIT_ORGANISATION}/spaces/${process.env.ORBIT_SPACE}`export async function call(method, path, body) { const isForm = body instanceof FormData for (let attempt = 1; ; attempt += 1) { const response = await fetch(`${BASE}${path}`, { method, headers: { authorization: `Bearer ${TOKEN}`, ...(body && !isForm ? { 'content-type': 'application/json' } : {}) }, body: isForm ? body : body === undefined ? undefined : JSON.stringify(body), }) if (response.status === 204) return null const json = await response.json().catch(() => ({})) if (response.ok) return json.data if (response.status >= 500 && attempt < 4) { await new Promise((resolve) => setTimeout(resolve, 1000 * attempt)) continue } const error = new Error(`${method} ${path} answered ${response.status}: ${json.error?.message ?? response.statusText}`) error.status = response.status error.details = json.error?.details throw error }}export async function findScope({ environment, region, locale }) { const environments = await call('GET', '/environments') const env = environments.find((entry) => entry.key === environment) if (!env) throw new Error(`No environment "${environment}"`) const regions = await call('GET', `/environments/${env.id}/regions`) const reg = regions.find((entry) => entry.key === region) if (!reg) throw new Error(`No region "${region}"`) const locales = await call('GET', `/environments/${env.id}/regions/${reg.id}/locales`) const loc = locales.find((entry) => entry.code === locale) if (!loc) throw new Error(`No language "${locale}" in ${region}`) return { environmentId: env.id, regionId: reg.id, localeId: loc.id, code: loc.code, path: `/environments/${env.id}/regions/${reg.id}/locales/${loc.id}`, }}Then the definitions. This is the Northwilds journal from Model your content. Each object is what you would POST:
export const components = [ { key: 'text', name: 'Text', group: 'Journal', fields: [{ key: 'text', name: 'Text', type: 'richtext', required: true }], }, { key: 'textSection', name: 'Text section', group: 'Journal', fields: [ { key: 'heading', name: 'Heading', type: 'text', required: true }, { key: 'level', name: 'Heading level', type: 'select', default: 'h2', options: [{ label: 'H2', value: 'h2' }, { label: 'H3', value: 'h3' }] }, { key: 'text', name: 'Text', type: 'richtext' }, ], }, { key: 'imageBlock', name: 'Image', group: 'Journal', fields: [ { key: 'image', name: 'Image', type: 'asset', required: true, allowedMimeTypes: ['image/*'] }, { key: 'caption', name: 'Caption', type: 'text' }, ], }, { key: 'gearList', name: 'Gear list', group: 'Gear', fields: [ { key: 'heading', name: 'Heading', type: 'text', required: true }, { key: 'items', name: 'Items', type: 'components', allowedComponents: ['gearItem'] }, ], }, { key: 'gearItem', name: 'Gear item', group: 'Gear', isRoot: false, fields: [ { key: 'name', name: 'Name', type: 'text', required: true }, { key: 'link', name: 'Link', type: 'link' }, ], },]export const contentTypes = [ { key: 'author', name: 'Author', fields: [ { key: 'bio', name: 'Biography', type: 'richtext' }, { key: 'photo', name: 'Photo', type: 'asset' }, ], }, { key: 'journalPost', name: 'Journal post', urlPrefix: '/journal', fields: [ { key: 'excerpt', name: 'Excerpt', type: 'textarea', validation: { maxLength: 300 } }, { key: 'publishedOn', name: 'Published on', type: 'date' }, { key: 'author', name: 'Author', type: 'reference', allowedContentTypes: ['author'] }, { key: 'cover', name: 'Cover image', type: 'asset' }, { key: 'topics', name: 'Topics', type: 'taxonomyTerms', taxonomyKey: 'topics' }, ], allowedComponents: ['text', 'textSection', 'imageBlock', 'gearList', 'sharedSection'], },]isRoot: falsekeepsgearItemout of the page's top level, so it is only offered inside a gear list.sharedSectioninallowedComponentslets editors place shared sections on posts.- Components come first in the file, because content types and slots name them.
Slider, Star rating, Code block and Palette fields take their settings in the same object:
{ key: 'tripFacts', name: 'Trip facts', fields: [ { key: 'difficulty', name: 'Difficulty', type: 'slider', validation: { min: 1, max: 10 }, step: 0.5, unit: 'of 10', default: 5 }, { key: 'rating', name: 'Guide rating', type: 'rating', validation: { max: 5 }, halfStars: true }, { key: 'mapEmbed', name: 'Map embed', type: 'code', languages: ['html'], defaultLanguage: 'html' }, { key: 'accent', name: 'Accent', type: 'palette', options: [{ label: 'Fjord blue', value: '#1F4E79' }, { label: 'Moss green', value: '#4A6B3A' }] }, ],}Saving refuses a slider whose lowest value isn't below its highest, a step bigger than the range, a rating with fewer than 3 or more than 10 stars, a starting language that isn't among languages, and a palette colour that isn't a hex code. cms-orbit schema validate checks the same before you push.
2Write the sync script
The script reads each definition, compares it with the space and creates or updates it. It prints what it would do and changes nothing unless you pass --apply. It stops before a field changes type, and before a field is removed unless you pass --allow-removals. It never deletes a component or content type: do that in CMS Orbit, which shows where each one is still used.
import { call } from './orbit.mjs'import { components, contentTypes } from './schema.mjs'const apply = process.argv.includes('--apply')const allowRemovals = process.argv.includes('--allow-removals')async function current(path) { try { return await call('GET', path) } catch (error) { if (error.status === 404) return null throw error }}function fieldChanges(before, after) { const old = new Map((before ?? []).map((field) => [field.key, field])) const next = new Map(after.map((field) => [field.key, field])) return [ ...[...next.keys()].filter((key) => !old.has(key)).map((key) => `+${key}`), ...[...old.keys()].filter((key) => !next.has(key)).map((key) => `-${key}`), ...[...next.keys()].filter((key) => old.has(key) && old.get(key).type !== next.get(key).type).map((key) => `~${key}`), ]}async function sync(kind, path, definition) { const existing = await current(`${path}/${definition.key}`) const changes = fieldChanges(existing?.fields, definition.fields) if (changes.some((change) => change.startsWith('~'))) { throw new Error(`${kind} ${definition.key}: a field changes type (${changes.join(' ')}). Add a new field instead.`) } if (!allowRemovals && changes.some((change) => change.startsWith('-'))) { throw new Error(`${kind} ${definition.key}: fields would be removed (${changes.join(' ')}). Run with --allow-removals once the website no longer reads them.`) } console.log(`${existing ? 'update' : 'create'} ${kind} ${definition.key} ${changes.join(' ')}`.trim()) if (!apply) return if (existing) { const { key, ...rest } = definition await call('PATCH', `${path}/${key}`, rest) } else { await call('POST', path, definition) if (definition.urlPrefix) await call('PATCH', `${path}/${definition.key}`, { urlPrefix: definition.urlPrefix }) }}for (const component of components) await sync('component', '/components', component)for (const type of contentTypes) await sync('content type', '/content-types', type)if (!apply) console.log('Dry run. Run again with --apply to make these changes.')3Run it
export ORBIT_TOKEN=cms_mt_…export ORBIT_ORGANISATION=<organisation id>export ORBIT_SPACE=<space id>node cms/sync-schema.mjscreate component text +textcreate component textSection +heading +level +textcreate component imageBlock +image +captioncreate component gearList +heading +itemscreate component gearItem +name +linkupdate content type authorcreate content type journalPost +excerpt +publishedOn +author +cover +topicsDry run. Run again with --apply to make these changes.+ is a new field, - a removed one. Check the list, then run node cms/sync-schema.mjs --apply. Running it again changes nothing that is already the same: a PATCH with identical fields does not move the schema version.
If the space refuses a definition, the script stops with the reason, such as PATCH /content-types/journalPost answered 400: Some entries live elsewhere, such as /lofoten-in-winter. Move every entry under /journal first, so no address changes. Status codes and their fixes are in Error codes.
4Run it from CI
Run the dry run on every pull request and apply on the main branch. This GitHub Actions workflow keeps the token in a repository secret:
name: CMS schemaon: pull_request: paths: ['cms/**'] push: branches: [main] paths: ['cms/**']jobs: schema: runs-on: ubuntu-latest env: ORBIT_TOKEN: ${{ github.event_name == 'push' && secrets.ORBIT_TOKEN || secrets.ORBIT_READ_TOKEN }} ORBIT_ORGANISATION: ${{ vars.ORBIT_ORGANISATION }} ORBIT_SPACE: ${{ vars.ORBIT_SPACE }} steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 24 - run: node cms/sync-schema.mjs ${{ github.event_name == 'push' && '--apply' || '' }}- Give pull requests a read-only token (
ORBIT_READ_TOKEN), so a pull request can never change the schema. - Tokens expire after at most 365 days. Note the date and renew it before then, or the job fails with
401. - After applying, regenerate the website's types with
npx cms-orbit generate --out src/cms/types.tsin the same pipeline, so a schema change that breaks the website fails its build. See SDK.
Change fields safely
Because the schema is shared by every environment, a change must work for the website that is live now and for the one you are about to deploy. Entries keep every value they hold; nothing is converted or erased.
--allow-removals. Values stay stored, and adding the key again brings them back.409, naming the pages.Field types has the full table under "Change or remove a field safely".
Several spaces
To keep a staging space and a production space alike, or one schema across many websites, run the same script once per space with a different ORBIT_SPACE. For a one-off copy of every definition from one space to another, use Download JSON in one space's settings and Import… in the other's: the import adds what is missing and leaves anything with the same key as it is. See Space settings.
Was this page helpful?