# Date & Time Fields

Seven field types store dates, times, durations, and system-managed audit timestamps. All share the [base field properties](/en/docs/tables-overview#base-field-properties).

| Type         | Stores                                                    |
| ------------ | --------------------------------------------------------- |
| `date`       | A calendar date, with optional time component.            |
| `datetime`   | A date plus time, timezone-aware.                         |
| `time`       | A time of day without a date.                             |
| `duration`   | An elapsed-time / work-hours value (stored in seconds).   |
| `created-at` | System-set timestamp captured when a record is created.   |
| `updated-at` | System-updated timestamp refreshed on every modification. |
| `deleted-at` | Soft-delete timestamp; NULL means the record is active.   |

## `date`

Calendar dates, optionally including a time component.

| Property      | Description                                                                      |
| ------------- | -------------------------------------------------------------------------------- |
| `format`      | Free-form display format string (e.g. `YYYY-MM-DD`, `MM/DD/YYYY`, `DD-MM-YYYY`). |
| `dateFormat`  | Display preset: `US`, `European`, or `ISO`.                                      |
| `timeFormat`  | Time display: `12-hour` or `24-hour`.                                            |
| `includeTime` | Boolean. When `true`, the date field also captures a time.                       |
| `timezone`    | IANA timezone identifier (e.g. `UTC`, `America/New_York`, `Europe/London`).      |
| `timeZone`    | Timezone setting accepting a specific zone or `local` (browser timezone).        |
| `default`     | Default date value for new records.                                              |

```yaml
- { id: 1, name: due_date, type: date, dateFormat: ISO, includeTime: false }
```

## `datetime`

Date plus time. Timezone-aware for accurate cross-region scheduling.

| Property     | Description                                                                      |
| ------------ | -------------------------------------------------------------------------------- |
| `format`     | Free-form display format string (e.g. `YYYY-MM-DD HH:mm`, `MM/DD/YYYY hh:mm A`). |
| `dateFormat` | Display preset: `US`, `European`, or `ISO`.                                      |
| `timeFormat` | Time display: `12-hour` or `24-hour`.                                            |
| `timezone`   | IANA timezone identifier.                                                        |
| `timeZone`   | Timezone setting accepting a specific zone or `local`.                           |
| `default`    | Default datetime value for new records.                                          |

```yaml
- { id: 2, name: published_at, type: datetime, timeFormat: 24-hour, timezone: UTC }
```

## `time`

Time-only values without a date. Used for schedules, opening hours, and time slots.

| Property     | Description                                          |
| ------------ | ---------------------------------------------------- |
| `timeFormat` | Time display: `12-hour` or `24-hour`.                |
| `default`    | Default time in `HH:MM:SS` format (e.g. `09:00:00`). |

```yaml
- { id: 3, name: start_time, type: time, required: true, timeFormat: 24-hour }
```

## `duration`

Elapsed time or work hours, stored as a number of seconds.

| Property        | Description                                              |
| --------------- | -------------------------------------------------------- |
| `format`        | Free-form display format string for the duration.        |
| `displayFormat` | Display preset: `h:mm`, `h:mm:ss`, or `decimal`.         |
| `default`       | Default duration value, in **seconds**, for new records. |

```yaml
- { id: 4, name: work_hours, type: duration, displayFormat: 'h:mm' }
```

## System Audit Timestamps

`created-at`, `updated-at`, and `deleted-at` are **system-managed** — their values are set automatically and cannot be edited manually. They take no type-specific properties beyond the base field properties (commonly `indexed: true`).

| Type         | Behavior                                                                                       |
| ------------ | ---------------------------------------------------------------------------------------------- |
| `created-at` | Captured once when the record is created. Read-only.                                           |
| `updated-at` | Refreshed automatically whenever the record is modified. Read-only.                            |
| `deleted-at` | Set when the record is soft-deleted. `NULL` indicates an active record; a timestamp = deleted. |

```yaml
fields:
  - { id: 5, name: created_at, type: created-at, indexed: true }
  - { id: 6, name: updated_at, type: updated-at, indexed: true }
  - { id: 7, name: deleted_at, type: deleted-at, indexed: true }
```

:::callout
**Soft-delete lifecycle.** Adding a `deleted-at` field enables Sovrium's soft-delete-by-default behavior: deleting a record sets the timestamp instead of removing the row, and `/restore` clears it. Pair with [`deleted-by`](/en/docs/user-audit-fields) to record who performed the deletion.
:::