> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stage.systems/llms.txt
> Use this file to discover all available pages before exploring further.

# Page schemas

> Editing needs no schema. Adding does. A per-site schema declares which fields are lists, what a new item looks like, and what the edit notch offers.

Two jobs, two mechanisms:

* **Editing** an existing field is anchor-driven. If it renders with `data-e-path`, it is editable.
* **Adding** needs to know the shape of the thing being added. That is the schema.

## Singleton or list

| Kind          | Example                         | The admin can                                     |
| ------------- | ------------------------------- | ------------------------------------------------- |
| **Singleton** | A title, an intro, a hero image | Edit in place                                     |
| **List**      | Logos, cards, FAQ rows, slides  | Add, reorder, remove, and edit each item in place |

The schema marks the lists and describes the item shape. Everything else is a singleton by default.

## A schema entry

`lib/admin-schema.ts` exports the object `mountAdmin` receives. Per component type:

```ts theme={null}
"feature-grid": {
  arrays: {
    "props.items": {
      kind: "modal",              // or "inline": a ghost row at the insert point
      addLabel: "Add feature",
      title: "New feature",
      noun: "feature",
      reorderable: true,          // drag handles; "strip" for one-at-a-time components
      form: [                     // what the Add form asks for
        { key: "title", label: "Title", type: "text", required: true },
        { key: "body",  label: "Body",  type: "textarea" },
        { key: "image", label: "Image", type: "media", videoKey: "imageVideo" },
      ],
    },
  },
  form: [                         // fields with no on-page anchor: the settings cog
    { key: "dark", label: "Dark text", type: "toggle" },
  ],
  notch: [ /* explicit notch entries, optional */ ],
  insert: "reload",               // only if the DOM derives from the list (dots, counts)
}
```

| Key      | Meaning                                                                                                                                                       |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `arrays` | Keyed by the dotted path of the list. `form` is the Add form. `reorderable` turns on drag, or the filmstrip for components that show one item at a time       |
| `form`   | The settings cog on the component: props the design does not render, such as a toggle or a hidden video                                                       |
| `notch`  | Explicit entries for the section's [edit notch](/developers/structure/edit-notch). Omitted, the admin derives one entry per addable list. `[]` means no notch |
| `insert` | How a new item arrives. Default: grafted in place with no reload. `"reload"` for components whose derived DOM cannot absorb a lone item                       |

Form field types: `text`, `textarea`, `url`, `toggle`, `select`, `list` (with `itemKey`), `media` (with `videoKey`). `showIf: { key, value }` hides a field until a toggle flips, and hidden fields skip validation.

## Reflected keys

A settings-cog field whose value the renderer mirrors straight onto the DOM (a `required` attribute, a `placeholder`) can be applied in place with no re-render. Anything else re-renders the component staged.

## What else the schema declares

| Section    | Declares                                                                                                  |
| ---------- | --------------------------------------------------------------------------------------------------------- |
| `pages`    | Per page slug or glob, the **section palette**: which section types a page accepts. Adds append a section |
| `articles` | The blog: base path and the `/` menu of content types. See [Blog](/developers/structure/blog)             |
| `forms`    | The form builder's `/` menu and the question types. See [Forms](/developers/structure/forms)              |

The schema is the site's. The admin package is generic and reads whatever it is handed.

## Next steps

<CardGroup cols={2}>
  <Card title="The edit notch" href="/developers/structure/edit-notch">
    The constraint and the contract.
  </Card>

  <Card title="Blog" href="/developers/structure/blog">
    Give a site articles.
  </Card>
</CardGroup>