# When the schema changes

Sites change after launch: a section goes, a field is renamed, a zone gets stricter. This page covers what stored content keeps when the code moves on, how the admin shows it, and what Publish refuses until an editor fixes it.

## What a change leaves behind

Smoodly never rewrites stored content when you deploy. A page, an entry or a global keeps what it held, and the admin compares it with the code you deployed. What it finds falls into two kinds: **broken** content blocks the next publish, **left over** content is only reported.

| Change | What stays stored | Publish |
| --- | --- | --- |
| `Remove a section` | Every placed copy of it. The canvas shows a placeholder; the site renders nothing for it. | Refused |
| `Rename or remove a field` | The old key and its value. The admin lists it under No longer in the schema; the new field starts empty. | Allowed, unless the new field is required: then Required until it is filled |
| `Change a field's type` | The old value. When it doesn't fit the new type, such as text in f.number(), the field shows an error. | Refused when it doesn't fit |
| `Remove a select option` | The value. It no longer fits the field. | Refused |
| `Tighten a zone` | Sections the zone no longer allows, and sections over its .max(). | Refused |
| `Remove a zone from a page type` | The zone's sections, no longer shown. | Allowed |
| `Remove an element` | Every copy of it inside richtext. Its card in the editor says the code no longer registers it. | Refused |
| `Drop an element from a toolset` | Every copy of it. It still renders, because a toolset only decides what editors can insert. | Allowed |
| `Remove a page type` | Its pages. The canvas shows the site's 404 until the page gets another type. | Refused |
| `Remove a collection` | Its entries. The admin has no editor for them, so register it again or delete them. | No editor |
| `Toggle .localized()` | Every value. See Localized fields. | Allowed |

An empty value always fits: a new required field on old content is a *Required* error, as it is for new content.

## Content health

*Settings › Content health* lists every page, entry and global that doesn't match the code. Every member can open it, because editors do most of the fixing. It checks when it opens and when you press *Rescan*.

Findings come in two sections, *Blocks publishing* and *Left over*. Each group is one change you made, like "Field `title` no longer in section `hero`", with the documents it touches under it. A row names the document, its languages and where the problem sits:

- *Draft* only: the next publish will be refused until it is fixed.
- *Live* only: the site runs on content the code no longer describes, and the draft is already fixed. Publishing clears it.
- Both: fix it in the draft, then publish.

*Open* goes to the document's editor. The page only points; fixes happen in the editors.

## In the editor

A document with findings shows a notice under the top bar: "2 problems block publishing · 1 left over from an older schema". The page editor marks each affected section in the *Page Outline*, red for broken and grey for left over, and the fixes are where the problems are:

- **An unknown section** shows as a placeholder on the canvas. Select it to see its stored values, each with *Copy*, and *Remove section*.
- **A value that doesn't fit** is an error on its field. Typing a new value replaces it.
- **Left-over keys** sit in a collapsed *No longer in the schema* group at the foot of the form, each with *Copy* and *Clear*.
- **A removed zone** is listed after the real zones with *Clear zone*.

Every fix is an ordinary draft edit: it autosaves, and *Discard changes* or the history undoes it.

## What Publish refuses

Publish refuses broken content with the problems listed, the same way it refuses an empty required field. Left-over content never blocks it. The check runs on the server, so an editor can't publish around it.

Live pages are not rewritten. After a deploy the stored live version stays as it was, and a section the code no longer registers renders nothing on the site. The next publish takes the fixed draft live.

## Renaming a field

Rename a field in two steps, so no editor loses a value. First put the new field in the schema where the old one was, and deploy:

File: `components/elements/Callout.schema.ts`

```ts
import { f, smoodly } from "smoodly";

export const calloutSchema = smoodly.schema.section({
  name: "callout",
  title: "Callout",
  fields: {
    // was `title`: stored values stay under the old key until an editor moves them
    heading: f.text(),
  },
});
```

Then, for each page *Content health* lists under "Field `title` no longer in section `callout`": copy the value from the *No longer in the schema* group into *Heading*, *Clear* the old key and publish.

There is no bulk rename in the admin yet. A tool that rewrote every page at once could break every live page with one wrong mapping, so its shape is still an open question. For many pages, a script can do it for your own site: walk `pages.list()`, read each page with `getTree`, move the value, write it back with `setTree` and publish, as [Content from code](https://smoodly.io/docs/getting-started/content-from-code.md) shows. Until it runs, a required field under the new name renders empty on the live site; nothing warns a visitor.

A rename also fails the type check wherever code writes the old name (`npx tsc --noEmit`; `npx astro check` on Astro, whose `astro build` does not type-check; a dev server or a build pushes the renamed schema to the space when it starts), such as the starter's `scripts/seed.ts`: its `node()` calls are typed from the section. The seed has already run, so update the name there or delete the script.

Next, [Localized fields](https://smoodly.io/docs/languages/localized-fields.md).
