> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/cloud/database/collections/create-schema.md).

# Create a schema

Create a collection — build its schema (fields and form) and publish it.

**Where:** Database → Collections → **Add New** · `/projects/<project>/db/schemas/new`

Every collection is defined by **two schemas** that you edit together:

* the **data schema** — what is stored and checked: fields, types and rules. It is JSON Schema with 17 field types: text (with formats like `email` and `uri`, and translatable text), integers, decimals, money, yes / no, dates, enums, tags, files, geolocation, free-form JSON, references to users, roles, taxonomy terms and other records, nested forms and arrays. Every type, its keywords and what the server refuses: [Field type reference](/codemash/cloud/database/schema/field-types.md).
* the **UI schema** — how the record form looks: **tabs** → **containers** → **cells** on a 12-column grid, each cell showing one field with its widget, label and form hints (placeholder, help, relative date bounds, …). What goes where: [Schema authoring guide](/codemash/cloud/database/schema.md).

## Before you start

* The Database module is on and has a default integration — see [Integrations](/codemash/cloud/integrations.md).
* You need `database:create` on `database:schema:all`.

## Steps

1. Open **Database → Collections** and press **Add New**. The builder opens as **New schema**, on the **Schema** tab, with an empty **Visual Builder**. The **List**, **Triggers** and **Settings** tabs open after the first save.

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-663c09fde7b1807ad14e7d981215077280c353a1%2Fcreate-schema-1.png?alt=media" alt="New schema: the tabs Schema, List, Triggers and Settings, an empty Schema name field, the inner tabs Visual Builder, Preview and JSON, and an empty builder; a Show fields panel button at the top right"><figcaption><p>A new, empty schema.</p></figcaption></figure>
2. Type the **Schema name**, for example `authors`. It becomes the collection name in API paths (`/database/collections/authors`).
3. Add the fields. Either:

   * **Visual Builder** — add a container, then drag fields from the **Form fields** panel (**Show fields panel**) into it: **Text**, **Number**, **Date**, **Select**, **Yes/No**, **File**, **Email**, **URI**, **Rating**, **Nested Form**, **Geo Location**, **Tags**, **Long text**, **HTML**, **Date & time**, **JSON** and **Array**. The gear icon of a field sets its label, whether it is required, and its limits; the number on the right (`6/12`) is its width. **Select** covers a fixed list and the four [reference](/codemash/cloud/database/schema/references.md) kinds (users, roles, taxonomy terms, records of a collection); **Nested Form** and **Array** nest up to five levels — see [Nested forms and arrays](/codemash/cloud/database/schema/nesting.md).
   * **JSON** → **Edit JSON** — paste the data schema into the top editor and the UI schema into the bottom one, then press **Save schemas' changes**. The button turns on only when both are valid JSON.

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-a1cc39dc5416403eadbc317a5544d1b0ef6ff303%2Fcreate-schema-2.png?alt=media" alt="The JSON tab in edit mode: the data schema of authors (name, country, born) in the top editor and the UI schema with one tab Author in the bottom editor"><figcaption><p>JSON → Edit JSON: the data schema on top, the UI schema below.</p></figcaption></figure>

   Example data schema for `authors`:

   ```json
   {
     "$schema": "https://norbix.ai/schemas/meta/v1.json",
     "title": "authors",
     "type": "object",
     "additionalProperties": true,
     "properties": {
       "name": { "type": "string", "maxLength": 200 },
       "country": { "type": "string", "maxLength": 100 },
       "born": { "type": "integer", "minimum": 0 }
     },
     "required": ["name"]
   }
   ```
4. Check the result in **Visual Builder** (the layout) and **Preview** (the form your team will fill).

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-dab6e84c63337f535b1be7f0bf64832cc7187120%2Fcreate-schema-3.png?alt=media" alt="Visual Builder of authors: one tab Author with a container that holds Name (Required, 6/12), Country (3/12) and Born (3/12)"><figcaption><p>The Visual Builder after the JSON was applied.</p></figcaption></figure>
5. Press **Save & publish**. To keep the schema unpublished for now, press **Create draft** instead; it then waits under **Schemas under development**.

   | Button             | What it does                                                                |
   | ------------------ | --------------------------------------------------------------------------- |
   | **Create draft**   | Saves the schema as a draft. No records can be added until it is published. |
   | **Save & publish** | Saves and publishes version 1; the collection is ready for records.         |
   | **Cancel**         | Goes back to the Collections list without saving.                           |

## Result

Cloud goes back to **Database → Collections**, and the new collection is listed as `Published · v1`. Click its name to open its empty [records list](/codemash/cloud/database/collections/records.md) and press **Add New** to [add the first record](/codemash/cloud/database/collections/add-records.md).

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-855bc1643ce9d9dec328ae449ddabd7a236f1b80%2Fcreate-schema-4.png?alt=media" alt="Data Collections list with books, archive_2024 and authors, all Published · v1; reviews under Schemas under development"><figcaption><p>The new collection authors in the list.</p></figcaption></figure>

The same schema drives the record form in Cloud and the checks on every API write: change it once, and both follow.

**Create with the AI assistant.** When the project has an AI assistant set up (see [AI](/codemash/cloud/ai.md)), **Create using AI Chat** appears next to **Schema name** and opens the assistant; describe the collection ("authors with a name, a country and a year of birth") and it drafts the fields into the builder. Nothing is saved until you press **Create draft** or **Save & publish**. From an MCP client, the same job is done by `apply_database_schema_bundle` — see [What agents can do](/codemash/ai/developers/what-agents-can-do.md).

## Change or remove it later

* **Edit** — row menu → **Edit schema**: change fields as a draft, then publish a new version — see [Edit a schema](/codemash/cloud/database/collections/edit-schema.md).
* **Settings** — the schema's **Settings** tab: description, **Soft delete**, **Records have an owner**, AI **Embed** — see [Edit a schema](/codemash/cloud/database/collections/edit-schema.md#change-or-remove-it-later).
* **Delete** — **Settings** tab → **Delete schema...**; the dialog asks you to paste the schema id and says how many records will be deleted with it — see [Edit a schema](/codemash/cloud/database/collections/edit-schema.md#change-or-remove-it-later).

A schema is created in the environment you are working in. To get it into PROD, build it in TEST and [promote](/codemash/cloud/project/settings/environments.md#promote-content-up-the-ladder) TEST → PROD. Names are unique per environment.

## Do it from code

```ts
const dataSchema = {
  $schema: 'https://norbix.ai/schemas/meta/v1.json',
  title: 'publishers', type: 'object', additionalProperties: true,
  properties: { name: { type: 'string', maxLength: 200 } },
  required: ['name'],
};
const uiSchema = {
  $schema: 'https://norbix.ai/schemas/ui/v1.json',
  metadata: { title: 'Publisher' },
  tabs: [{ tabName: 'Publisher', containers: [{ cells: [
    { colSpan: 12, element: { fieldId: 'name', meta: { widget: 'text', label: 'Name', required: true } } },
  ] }] }],
};
const { id } = await norbix.hub.database.saveDatabaseSchema({
  schemaName: 'publishers',
  dataSchema: JSON.stringify(dataSchema),
  visualSchema: JSON.stringify(uiSchema),
});
await norbix.hub.database.publishDatabaseSchema({ id });
```

```sh
norbix hub database schema save --schemaName magazines --dataSchema "$(cat magazines.data.json)" --visualSchema "$(cat magazines.ui.json)"
```

The client setup is on the [Database page](/codemash/cloud/database.md#use-it-from-code). API: [Save Database Schema](/codemash/api-reference/database/schemas/save-database-schema.md) · [Publish Database Schema](/codemash/api-reference/database/schemas/publish-database-schema.md)