# Replace a database's schema and views

`PUT /v1/databases/{id}/definition`

Applies a whole definition (what fromBase reads from a .base file): properties and views with a known id are updated, new ones created, live ones missing from it deleted. Row values are not touched.

Scope: `docs:write`. Undoable.

## Request

```bash
curl -X PUT "https://api.lydie.co/v1/databases/01JCQ3V5MZ8G4ZK2X7T9R6N1PB/definition" \
  -H "Authorization: Bearer $LYDIE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": {
      "config": {},
      "properties": [
        {
          "id": "01JCQ3V5MZ8G4ZK2X7T9R6N1PB",
          "name": "Notes",
          "type": "title",
          "key": "string"
        }
      ],
      "views": [
        {
          "id": "01JCQ3V5MZ8G4ZK2X7T9R6N1PB",
          "name": "Notes",
          "type": "table",
          "config": {}
        }
      ]
    }
  }'
```

## Path parameters

- `id` (ULID, required)

## Body

- `definition` (object, required)
  - `config` (DatabaseConfigInput, required)
    - `filter` (FilterNode, optional, nullable): Default: `null`.
    - `templateIds` (ULID[], optional): Default: `[]`.
    - `extra` (object, optional): Default: `{}`.
  - `properties` (object[], required)
    - `id` (ULID, required)
    - `name` (string, required): (1–200 chars)
    - `type` (string, required): One of: `title`, `text`, `number`, `select`, `multiSelect`, `status`, `date`, `checkbox`, `url`, `email`, `phone`, `person`, `files`, `relation`, `rollup`, `formula`, `uniqueId`, `createdTime`, `updatedTime`, `createdBy`, `updatedBy`.
    - `key` (string, required): (1–128 chars)
    - `config` (PropertyConfigInput, optional): Default: `{}`.
      - `options` (SelectOptionInput[], optional): select, multiSelect, status
        - `id` (ULID, required)
        - `name` (string, required): (1–200 chars)
        - `color` (string, optional): One of: `default`, `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `red`. Default: `"default"`.
        - `group` (string, optional): One of: `todo`, `inProgress`, `complete`.
      - `numberFormat` (string, optional): One of: `number`, `integer`, `commas`, `percent`, `currency`.
      - `decimals` (integer, optional): (0–10)
      - `currency` (string, optional): ISO 4217 code, with numberFormat currency (3–3 chars)
      - `includeTime` (boolean, optional): date: values carry a time
      - `range` (boolean, optional): date: values may carry an end (start/end)
      - `relation` (RelationConfigInput, optional)
        - `databaseId` (ULID, required): The database whose rows this relation points at.
        - `twoWay` (boolean, optional): Default: `false`.
        - `reversePropertyId` (ULID, optional, nullable): The synced property on the other database (two-way relations). Default: `null`.
        - `limit` (string, optional): One of: `one`, `many`. Default: `"many"`.
      - `rollup` (RollupConfigInput, optional)
        - `relationPropertyId` (ULID, required)
        - `targetPropertyId` (ULID, required): A property of the related database.
        - `function` (string, required): One of: `showOriginal`, `showUnique`, `count`, `countValues`, `countUnique`, `countEmpty`, `countNotEmpty`, `percentEmpty`, `percentNotEmpty`, `sum`, `average`, `median`, `min`, `max`, `range`, `earliest`, `latest`, `checked`, `unchecked`, `percentChecked`, `percentUnchecked`.
      - `expression` (string, optional): formula: an Obsidian Bases expression
      - `prefix` (string, optional): uniqueId: shown before the number ("LYD" → LYD-12) (≤ 16 chars)
      - `extra` (object, optional)
  - `views` (object[], required)
    - `id` (ULID, required)
    - `name` (string, required): (1–200 chars)
    - `type` (string, required): One of: `table`, `board`, `list`, `calendar`, `gallery`.
    - `config` (ViewConfigInput, required)
      - `filter` (FilterNode, optional, nullable): Default: `null`.
      - `sorts` (object[], optional): Default: `[]`.
        - `propertyId` (ULID, required)
        - `direction` (string, optional): One of: `asc`, `desc`. Default: `"asc"`.
      - `groupBy` (GroupByInput, optional, nullable): Default: `null`.
        - `propertyId` (ULID, required)
        - `direction` (string, optional): One of: `asc`, `desc`. Default: `"asc"`.
        - `order` (string[], optional)
        - `hideEmpty` (boolean, optional): Hide groups with no rows (board columns).
        - `dateBucket` (string, optional): Date grouping; default month. One of: `day`, `week`, `month`, `year`.
        - `collapsed` (string[], optional)
      - `subGroupBy` (GroupByInput, optional, nullable): Board swimlanes. Default: `null`.
        - `propertyId` (ULID, required)
        - `direction` (string, optional): One of: `asc`, `desc`. Default: `"asc"`.
        - `order` (string[], optional)
        - `hideEmpty` (boolean, optional): Hide groups with no rows (board columns).
        - `dateBucket` (string, optional): Date grouping; default month. One of: `day`, `week`, `month`, `year`.
        - `collapsed` (string[], optional)
      - `columns` (ViewColumnInput[], optional): Default: `[]`.
        - `propertyId` (ULID, required)
        - `visible` (boolean, optional): Default: `true`.
        - `width` (integer, optional): (20–2000)
      - `limit` (integer, optional, nullable): Default: `null`. (≥ 1)
      - `summaries` (object, optional): propertyId → summary name Default: `{}`.
      - `layout` (ViewLayoutInput, optional): Default: `{}`.
        - `rowHeight` (string, optional): table One of: `short`, `medium`, `tall`, `extra`.
        - `wrapCells` (boolean, optional): table
        - `cardSize` (integer, optional): board, gallery: px (50–1000)
        - `cover` (object, optional, nullable): board, gallery: the card image
        - `coverFit` (string, optional): One of: `cover`, `contain`.
        - `coverAspectRatio` (number, optional): (0.1–10)
        - `markers` (string, optional): list One of: `bullet`, `number`, `none`.
        - `calendarPropertyId` (ULID, optional): calendar: the date property placing rows
        - `calendarMode` (string, optional): One of: `month`, `week`.
        - `showWeekends` (boolean, optional)
        - `colorColumns` (boolean, optional): board
      - `extra` (object, optional): Default: `{}`.

## Response

- `database` (Database, required)
  - `id` (ULID, required)
  - `workspaceId` (string, required): (1–64 chars)
  - `config` (DatabaseConfig, required)
    - `filter` (FilterNode, required, nullable): Default: `null`.
    - `templateIds` (ULID[], required): Default: `[]`.
    - `extra` (object, required): Default: `{}`.
  - `createdAt` (timestamp, required)
  - `updatedAt` (timestamp, required)
  - `deletedAt` (timestamp, required, nullable)
  - `createdBy` (string, optional, nullable): (≥ 1 chars)
  - `updatedBy` (string, optional, nullable): (≥ 1 chars)
- `properties` (DatabaseProperty[], required)
  - `id` (ULID, required)
  - `workspaceId` (string, required): (1–64 chars)
  - `databaseId` (ULID, required)
  - `name` (string, required): Display name (Bases displayName). (1–200 chars)
  - `type` (string, required): One of: `title`, `text`, `number`, `select`, `multiSelect`, `status`, `date`, `checkbox`, `url`, `email`, `phone`, `person`, `files`, `relation`, `rollup`, `formula`, `uniqueId`, `createdTime`, `updatedTime`, `createdBy`, `updatedBy`.
  - `key` (string, required): Stored types: the frontmatter key holding the value. Formulas, rollups, createdBy and updatedBy: the formula name in the .base file. Unused for title and created/updated time. (1–128 chars)
  - `config` (PropertyConfig, required)
    - `options` (SelectOption[], optional): select, multiSelect, status
      - `id` (ULID, required)
      - `name` (string, required): (1–200 chars)
      - `color` (string, required): One of: `default`, `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `red`. Default: `"default"`.
      - `group` (string, optional): One of: `todo`, `inProgress`, `complete`.
    - `numberFormat` (string, optional): One of: `number`, `integer`, `commas`, `percent`, `currency`.
    - `decimals` (integer, optional): (0–10)
    - `currency` (string, optional): ISO 4217 code, with numberFormat currency (3–3 chars)
    - `includeTime` (boolean, optional): date: values carry a time
    - `range` (boolean, optional): date: values may carry an end (start/end)
    - `relation` (RelationConfig, optional)
      - `databaseId` (ULID, required): The database whose rows this relation points at.
      - `twoWay` (boolean, required): Default: `false`.
      - `reversePropertyId` (ULID, required, nullable): The synced property on the other database (two-way relations). Default: `null`.
      - `limit` (string, required): One of: `one`, `many`. Default: `"many"`.
    - `rollup` (RollupConfig, optional)
      - `relationPropertyId` (ULID, required)
      - `targetPropertyId` (ULID, required): A property of the related database.
      - `function` (string, required): One of: `showOriginal`, `showUnique`, `count`, `countValues`, `countUnique`, `countEmpty`, `countNotEmpty`, `percentEmpty`, `percentNotEmpty`, `sum`, `average`, `median`, `min`, `max`, `range`, `earliest`, `latest`, `checked`, `unchecked`, `percentChecked`, `percentUnchecked`.
    - `expression` (string, optional): formula: an Obsidian Bases expression
    - `prefix` (string, optional): uniqueId: shown before the number ("LYD" → LYD-12) (≤ 16 chars)
    - `extra` (object, optional)
  - `sortKey` (string, required): (1–256 chars)
  - `createdAt` (timestamp, required)
  - `updatedAt` (timestamp, required)
  - `deletedAt` (timestamp, required, nullable)
  - `createdBy` (string, optional, nullable): (≥ 1 chars)
  - `updatedBy` (string, optional, nullable): (≥ 1 chars)
- `views` (DatabaseView[], required)
  - `id` (ULID, required)
  - `workspaceId` (string, required): (1–64 chars)
  - `databaseId` (ULID, required)
  - `name` (string, required): (1–200 chars)
  - `type` (string, required): One of: `table`, `board`, `list`, `calendar`, `gallery`.
  - `config` (ViewConfig, required)
    - `filter` (FilterNode, required, nullable): Default: `null`.
    - `sorts` (object[], required): Default: `[]`.
      - `propertyId` (ULID, required)
      - `direction` (string, required): One of: `asc`, `desc`. Default: `"asc"`.
    - `groupBy` (GroupBy, required, nullable): Default: `null`.
      - `propertyId` (ULID, required)
      - `direction` (string, required): One of: `asc`, `desc`. Default: `"asc"`.
      - `order` (string[], optional)
      - `hideEmpty` (boolean, optional): Hide groups with no rows (board columns).
      - `dateBucket` (string, optional): Date grouping; default month. One of: `day`, `week`, `month`, `year`.
      - `collapsed` (string[], optional)
    - `subGroupBy` (GroupBy, required, nullable): Board swimlanes. Default: `null`.
      - `propertyId` (ULID, required)
      - `direction` (string, required): One of: `asc`, `desc`. Default: `"asc"`.
      - `order` (string[], optional)
      - `hideEmpty` (boolean, optional): Hide groups with no rows (board columns).
      - `dateBucket` (string, optional): Date grouping; default month. One of: `day`, `week`, `month`, `year`.
      - `collapsed` (string[], optional)
    - `columns` (ViewColumn[], required): Default: `[]`.
      - `propertyId` (ULID, required)
      - `visible` (boolean, required): Default: `true`.
      - `width` (integer, optional): (20–2000)
    - `limit` (integer, required, nullable): Default: `null`. (≥ 1)
    - `summaries` (object, required): propertyId → summary name Default: `{}`.
    - `layout` (ViewLayout, required): Default: `{}`.
      - `rowHeight` (string, optional): table One of: `short`, `medium`, `tall`, `extra`.
      - `wrapCells` (boolean, optional): table
      - `cardSize` (integer, optional): board, gallery: px (50–1000)
      - `cover` (object, optional, nullable): board, gallery: the card image
      - `coverFit` (string, optional): One of: `cover`, `contain`.
      - `coverAspectRatio` (number, optional): (0.1–10)
      - `markers` (string, optional): list One of: `bullet`, `number`, `none`.
      - `calendarPropertyId` (ULID, optional): calendar: the date property placing rows
      - `calendarMode` (string, optional): One of: `month`, `week`.
      - `showWeekends` (boolean, optional)
      - `colorColumns` (boolean, optional): board
    - `extra` (object, required): Default: `{}`.
  - `sortKey` (string, required): (1–256 chars)
  - `createdAt` (timestamp, required)
  - `updatedAt` (timestamp, required)
  - `deletedAt` (timestamp, required, nullable)
  - `createdBy` (string, optional, nullable): (≥ 1 chars)
  - `updatedBy` (string, optional, nullable): (≥ 1 chars)

```json
{
  "database": {
    "id": "01JCQ3V5MZ8G4ZK2X7T9R6N1PB",
    "workspaceId": "01JCQ3TZ0WJ8K4M2X7T9R6N1PA",
    "config": {
      "filter": null,
      "templateIds": [],
      "extra": {}
    },
    "createdAt": "2026-11-12T09:30:00.000Z",
    "updatedAt": "2026-11-12T09:30:00.000Z",
    "deletedAt": null,
    "createdBy": null,
    "updatedBy": null
  },
  "properties": [
    {
      "id": "01JCQ3V5MZ8G4ZK2X7T9R6N1PB",
      "workspaceId": "01JCQ3TZ0WJ8K4M2X7T9R6N1PA",
      "databaseId": "01JCQ3V5MZ8G4ZK2X7T9R6N1PB",
      "name": "Notes",
      "type": "title",
      "key": "string",
      "config": {
        "options": [
          null
        ],
        "numberFormat": "number",
        "decimals": 0,
        "currency": "string",
        "includeTime": false,
        "range": false,
        "relation": {
          "databaseId": "01JCQ3V5MZ8G4ZK2X7T9R6N1PB",
          "twoWay": false,
          "reversePropertyId": null,
          "limit": "one"
        },
        "rollup": {
          "relationPropertyId": "01JCQ3V5MZ8G4ZK2X7T9R6N1PB",
          "targetPropertyId": "01JCQ3V5MZ8G4ZK2X7T9R6N1PB",
          "function": "showOriginal"
        },
        "expression": "string",
        "prefix": "string",
        "extra": {}
      },
      "sortKey": "a0",
      "createdAt": "2026-11-12T09:30:00.000Z",
      "updatedAt": "2026-11-12T09:30:00.000Z",
      "deletedAt": null,
      "createdBy": null,
      "updatedBy": null
    }
  ],
  "views": [
    {
      "id": "01JCQ3V5MZ8G4ZK2X7T9R6N1PB",
      "workspaceId": "01JCQ3TZ0WJ8K4M2X7T9R6N1PA",
      "databaseId": "01JCQ3V5MZ8G4ZK2X7T9R6N1PB",
      "name": "Notes",
      "type": "table",
      "config": {
        "filter": null,
        "sorts": [],
        "groupBy": null,
        "subGroupBy": null,
        "columns": [],
        "limit": null,
        "summaries": {},
        "layout": {},
        "extra": {}
      },
      "sortKey": "a0",
      "createdAt": "2026-11-12T09:30:00.000Z",
      "updatedAt": "2026-11-12T09:30:00.000Z",
      "deletedAt": null,
      "createdBy": null,
      "updatedBy": null
    }
  ]
}
```

Errors use the envelope described at https://developers.lydie.co/errors.md.