{
  "slug": "settings-schema",
  "title": "Schema settings",
  "description": "Edit collections and field definitions live — the same schema you'd write in cms.config.ts, but from the admin UI. Only visible when schema-edit is enabled.",
  "category": "settings",
  "order": 13,
  "locale": "en",
  "translationGroup": "9e6d0b55-ec16-4284-86ca-acb19c70c7bc",
  "helpCardId": null,
  "content": "## Where it is\n\n**Settings → Schema** (`/admin/settings?tab=schema`) — only visible when `schemaEditEnabled` is true in site config. For production sites this is usually off; for dev and onboarding it's on.\n\n## What the tab lets you do\n\nAdd, remove, reorder, and retype fields on collections without editing `cms.config.ts` by hand. Changes take effect immediately — no restart, no build step.\n\nThe tab lists every collection with:\n\n- **Name** (internal id) and **label** (display name)\n- **Field count**\n- **Edit schema** button — drills into the field editor\n- **+ New collection** — scaffolds a new collection with your chosen fields and `kind`\n\n## Editing a collection\n\nClick **Edit schema** on any collection. The editor shows:\n\n- **Collection meta** — name, label, `kind` (page / snippet / data / form / global), description, `urlPrefix`, `urlPattern`, `previewable`\n- **Fields** — drag to reorder, click to edit, trash icon to remove\n- **Add field** — pick a field type from the palette\n- **Blocks** — if the collection uses the `blocks` field type, edit the block registry here\n\nSave to write changes. The CMS updates the in-memory schema, regenerates `webhouse-schema.json`, and fires the save hook to any downstream consumers.\n\n## Field types you can add\n\n`text`, `textarea`, `richtext`, `number`, `boolean`, `date`, `image`, `image-gallery`, `video`, `audio`, `htmldoc`, `file`, `interactive`, `column-slots`, `map`, `select`, `tags`, `relation`, `array`, `object`, `blocks`.\n\nEach field has a standard set of options (required, default, description) plus type-specific options (`select` has `options[]`, `relation` has `collection`, `array` has `fields[]`, etc.).\n\n## The care-required operations\n\nSome schema changes can silently break existing content. The tab warns before you commit, but know what you're doing:\n\n- **Renaming a field** — existing documents still have the old key in their `data` object. Either rename via a migration script or leave the old field (the CMS ignores keys not in the schema — the data is still there, just not shown in the editor).\n- **Removing a field** — the data stays on disk, the editor just hides it. Add the field back any time to see the data return.\n- **Changing a field type** — HIGH RISK. A richtext field's markdown won't fit into a text field; a relation turned into tags loses the references. The tab blocks the most destructive type changes; others show a warning.\n- **Changing `kind`** — e.g. `page` → `data` removes URL generation. Existing URLs 404 after the next deploy. Set up redirects first.\n- **Removing a collection** — don't. Trash the documents first, then remove. Otherwise the data files stay on disk orphaned.\n\n## Re-export the schema for non-TS consumers\n\nIf your project has non-TypeScript consumers (Java, .NET, PHP, Python, Ruby, Go), the `webhouse-schema.json` file is the contract. **Any schema change via this tab re-generates that file automatically and writes it to the project root.**\n\nCommit both `cms.config.ts` and `webhouse-schema.json` in the same commit. See [Framework consumers](/docs/framework-consumers) for why this matters.\n\n## Disabling schema edit\n\nFor production sites, set `SCHEMA_EDIT_ENABLED=false` (or remove the env var). The tab disappears from the sidebar. Editors can't change the schema; only a developer with repo access can.\n\n## Related\n\n- [Collections](/docs/collections) — conceptual overview of collections\n- [Field types](/docs/field-types) — full field type reference\n- [Collection metadata](/docs/collection-metadata) — the `kind` and `description` rules\n- [Framework consumers](/docs/framework-consumers) — why `webhouse-schema.json` must stay in sync",
  "excerpt": "Where it is\n\nSettings → Schema (/admin/settings?tab=schema) — only visible when schemaEditEnabled is true in site config. For production sites this is usually off; for dev and onboarding it's on.\n\n What the tab lets you do\n\nAdd, remove, reorder, and retype fields on collections without editing cms.c",
  "seo": {
    "metaTitle": "Schema settings — webhouse.app Docs",
    "metaDescription": "Edit collection schemas live from the admin UI — add, remove, reorder, and retype fields without restarting.",
    "keywords": [
      "webhouse",
      "cms",
      "settings",
      "schema",
      "collections",
      "fields",
      "kind",
      "cms.config.ts"
    ]
  },
  "createdAt": "2026-04-15T22:16:00.000Z",
  "updatedAt": "2026-04-15T22:16:00.000Z"
}