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

# YAML Reference

> Comprehensive reference for every attribute in a Knowledge Object definition.

# Knowledge Object YAML Reference

This page documents every attribute available in a Knowledge Object YAML definition. Each file declares **one object per YAML document**; you can define multiple objects in one file by separating them with `---`.

## Top-level structure

```yaml theme={null}
name: string            # Object name, unique per project (required)
description: string     # (Optional) Human-readable description
fields:                 # Field definitions (required, at least one)
settings:               # (Optional) Object settings
actions:                # (Optional) Action definitions
```

A minimal object needs a `name` and at least one field, and at least one of those fields must be a primary key:

```yaml theme={null}
name: Tag
fields:
  - name: slug
    type: str
    primary_key: true
  - name: label
    type: str
```

***

## `fields`

The list of columns that make up the object. Every field is validated on deploy; an unknown attribute or an unsupported type fails the deploy.

| Attribute      | Type   | Default | Description                                                                                                   |
| -------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------- |
| `name`         | string | —       | Field name (required).                                                                                        |
| `type`         | string | —       | Field type (required). One of the [supported types](#field-types).                                            |
| `primary_key`  | bool   | `false` | Whether the field is part of the object's primary key.                                                        |
| `optional`     | bool   | `false` | Whether the field is nullable / may be omitted on create.                                                     |
| `mutable`      | bool   | `true`  | Whether the value can be changed after creation.                                                              |
| `default`      | any    | `null`  | Default value applied at the database level when the field is omitted.                                        |
| `db_column`    | string | `null`  | (Optional) Override the underlying ClickHouse column name.                                                    |
| `db_type`      | string | `null`  | (Optional) Override the underlying ClickHouse column type.                                                    |
| `relationship` | list   | `null`  | (Optional) Declares the field as a [relationship](#relationships) to another object.                          |
| `options`      | list   | `null`  | (Optional, `str` only) Allowed values; renders a dropdown and is validated on write. See [Options](#options). |

### Field types

| Type       | Description           |
| ---------- | --------------------- |
| `int`      | Integer               |
| `str`      | String                |
| `float`    | Floating-point number |
| `bool`     | Boolean               |
| `datetime` | Timestamp             |
| `date`     | Calendar date         |

By default each type maps to a sensible ClickHouse column type. Use [`db_type`](#custom-database-types) to override the exact type.

### Primary keys

At least one field must have `primary_key: true`. The combination of primary key fields uniquely identifies an instance, and it is used to compute the stable instance key (`_key`).

* Primary key fields **cannot be optional**.
* Primary key fields are **immutable** — attempting to change one through the API is an error. A different primary key is a different instance.

```yaml theme={null}
fields:
  - name: order_id
    type: int
    primary_key: true
  - name: line_no
    type: int
    primary_key: true   # composite primary key
  - name: quantity
    type: int
```

### Defaults

`default` sets a **database-level default** that ClickHouse applies whenever the field is omitted from an insert. This means the default is enforced regardless of how the instance is created — through the API, or directly against the table.

Because it is a database expression, you can use functional defaults:

```yaml theme={null}
fields:
  - name: created_at
    type: datetime
    default: now()        # evaluated by the database on insert
  - name: status
    type: str
    default: active
  - name: is_active
    type: bool
    default: true
```

<Note>
  A field with a `default` may be omitted when creating an instance — the database fills it in. Functional defaults such as `now()` can only be produced at insert time, so the client should leave the field out rather than sending a value.
</Note>

### Mutability

Set `mutable: false` to freeze a field after the instance is created. Non-primary-key fields are mutable by default.

```yaml theme={null}
fields:
  - name: external_ref
    type: str
    mutable: false   # set once at creation, never updated
```

### Custom database columns and types

Use `db_column` and `db_type` to control the underlying ClickHouse storage independently of the field name and logical type:

```yaml theme={null}
fields:
  - name: amount
    type: float
    db_type: Decimal(18, 2)   # store as an exact decimal
  - name: label
    type: str
    db_column: display_label  # store under a different column name
```

### Relationships

A relationship field points at **another object's instance**. It is metadata only — there is no database-level foreign key. The field itself is a plain string that stores the target instance's key (`_key`).

* The field's `type` must be `str`.
* `relationship` must reference **exactly one** target object, by name.

```yaml theme={null}
name: Company
fields:
  - name: id
    type: int
    primary_key: true
  - name: name
    type: str
  - name: owner
    type: str
    optional: true
    relationship:
      - object: Person   # `owner` stores the _key of a Person instance
```

At read time you can ask the API to resolve relationships (one level deep) via the `add_relationships` flag — see the [Instance API](/reference/knowledge-objects/api#get-instance). In the UI, a relationship field is rendered as a picker over the target object's instances, using the target's [`label_column`](#settings) for display.

### Options

A `str` field can declare a fixed set of allowed values with `options`. The UI renders it as a dropdown instead of a free-text input, and the API rejects any create/update whose value is outside the list.

```yaml theme={null}
fields:
  - name: gender
    type: str
    options:
      - male
      - female
      - other
```

* `options` is only valid on `str` fields, and must not be empty.
* Writing an instance with a value not in `options` returns `400`.

***

## `settings`

Object-level settings. All are optional.

| Attribute        | Type   | Default      | Description                                                             |
| ---------------- | ------ | ------------ | ----------------------------------------------------------------------- |
| `object_type`    | string | `STANDALONE` | `STANDALONE` (managed instances) or `BACKED` (backed by a dataset).     |
| `backed_dataset` | string | `null`       | Alias of the backing dataset — required when `object_type` is `BACKED`. |
| `store_versions` | bool   | `false`      | Whether previous instance versions are retained.                        |
| `icon`           | string | `null`       | Icon name used to represent the object in the UI.                       |
| `label_column`   | string | `null`       | Which field to display as an instance's human label in the UI.          |

```yaml theme={null}
settings:
  icon: users
  label_column: name
  store_versions: true
```

* **`label_column`** must name one of the object's fields. It is used wherever an instance is shown by name — most importantly in relationship pickers.
* **`icon`** is purely for UI presentation.
* **`store_versions`** keeps superseded versions of an instance available in history. With it off, old versions may be compacted away over time (history becomes best-effort).

<Warning>
  `BACKED` objects (`object_type: BACKED`, backed by a dataset) are not yet generally available. Define `STANDALONE` objects — the default — for managed instances.
</Warning>

***

## `actions`

Actions bind a named operation on the object to a Python handler function in your repository.

| Attribute     | Type   | Description                                                       |
| ------------- | ------ | ----------------------------------------------------------------- |
| `name`        | string | Action name (required).                                           |
| `description` | string | (Optional) Human-readable description.                            |
| `handler`     | string | Reference to the handler, in the form `path/to/file.py:function`. |

```yaml theme={null}
actions:
  - name: send_welcome_email
    description: Send a welcome email to the employee.
    handler: objects/employee_actions.py:send_welcome_email
```

The `handler` must point at a Python file and function in your repository. Changing an object's actions does **not** trigger a schema migration — only field and setting changes do.

<Info>
  Executing actions via the API is on the roadmap; today, actions are declared and validated as part of the object definition.
</Info>

***

## Full example

```yaml objects/employee.yaml theme={null}
name: Employee
description: A person employed by the company.

fields:
  - name: id
    type: int
    primary_key: true
  - name: name
    type: str
  - name: email
    type: str
    optional: true
  - name: department
    type: str
    optional: true
    relationship:
      - object: Department
  - name: salary
    type: float
    db_type: Decimal(18, 2)
  - name: hired_at
    type: datetime
    default: now()
  - name: is_active
    type: bool
    default: true

settings:
  icon: users
  label_column: name
  store_versions: true

actions:
  - name: send_welcome_email
    description: Send a welcome email to the employee.
    handler: objects/employee_actions.py:send_welcome_email
```

***

## Deploying multiple objects

To define more than one object in a single file, separate documents with `---`:

```yaml objects/hr.yaml theme={null}
name: Department
fields:
  - name: id
    type: int
    primary_key: true
  - name: name
    type: str
settings:
  label_column: name
---
name: Employee
fields:
  - name: id
    type: int
    primary_key: true
  - name: department
    type: str
    relationship:
      - object: Department
```

Each object still becomes its own identity, definition, and ClickHouse table. Object names must be unique within the file and within the project.

## Next steps

* [Overview](/reference/knowledge-objects/overview) — concepts, branching, and the lifecycle.
* [Instance API](/reference/knowledge-objects/api) — managing instances of your objects.