# Type definition (/catalog/type-definition)

Every key a type definition takes, the rule each must meet and the answer when one is broken, including the display hints that say how a type's items are shown.



**Marfa refuses a definition that breaks a rule with `400 invalid_schema`,** naming the path of each broken key in `details.errors`, unless the rule names another answer. [Define a type](/build/define-a-type) registers one, and [Field kinds](/catalog/field-kinds) holds the rules for `fields` and `tables`. `marfa types check` applies them [before you register](/build/check-type-definitions).

## Keys [#keys]

A registration takes these keys and no others. A replacement takes its `id` from the path, and its body may carry the `provenance` and `ancestor_guidance` a read gave. `GET /types/{id}` answers display hints and the three policies after inheritance, and `GET /types` only those a type sets itself. A read also answers `provenance`, whose `origin` is `platform`, `registered`, `plugin` or `unknown`, and whose `plugin` names the plugin that installed the type, or is `null`.

| Key | Rule |
| - | - |
| `id` | Required to register. See [Identifier](#identifier). An otherwise valid, permitted registration of one already registered is refused `409 type_exists`. |
| `fields` | Required, an object of field definitions. Refused `400 missing_required_field` when missing. |
| `required` | A list of field names the type or an ancestor declares, the same as `required: true` on each. |
| `version` | A whole number of 0 or more that Marfa never changes. Defaults to 0. |
| `description`, `guidance` | See [Descriptions and guidance](#descriptions-and-guidance). |
| `tables` | An object of tables by name. |
| `label`, `plural` | See [Label and plural](#label-and-plural). |
| `parent` | See [Parent and inheritance](#parent-and-inheritance). |
| `display_hints`, `roles`, `link_field` | See the sections of the same name. |
| `merge_policy`, `version_policy`, `retention_policy` | See the three policy sections below. |

## Identifier [#identifier]

* **Grammar:** two or more dot-separated segments, each starting with a lowercase letter and holding lowercase letters, digits, hyphens and underscores. At most 128 characters, and exactly two segments after `app`, as in `app.readinglist.entry`. Anything else is `400 validation_error`.
* **`core`, `system` and `marfa`:** refused `403 forbidden`, whatever the credential.
* **`common`:** a new type is refused `403 forbidden` naming `marfa plugins install`, since only a [plugin](/use/install-a-plugin) adds one.
* **An `app.<vendor>` someone else holds:** refused `403 forbidden` ([Access](/build/access#an-apps-own-types)).
* **Other reserved roots:** every root below except `app`, `user`, `common`, `core`, `system` and `marfa` is refused `400 validation_error`. A root is the whole first segment, so `core-pub` is allowed.

`app`, `audit`, `backups`, `blobs`, `common`, `config`, `connectors`, `content`, `core`, `edge`, `grants`, `instance`, `items`, `keys`, `marfa`, `metadata`, `profile`, `schema`, `sign_ins`, `space`, `system`, `user`, `webhooks`

## Label and plural [#label-and-plural]

Each is optional and at most 100 characters.

* **`label`** names one item, such as `Recipe`. Left out, Marfa makes it from the identifier's last segment: `user.reading-list` is `Reading List`.
* **`plural`** names a list, such as `Recipes`. Left out, Marfa makes it by the regular English rule, so `Story` makes `Stories`. Declare it where that is wrong, as in `People`.

## Descriptions and guidance [#descriptions-and-guidance]

`guidance` is optional Markdown that tells an agent or an app builder how to use the type. Each text is at most this many Unicode code points:

| Text | At most |
| - | - |
| A type's `description` | 200 |
| A field's or an `items_fields` member's `description` | 300 |
| A status word's `description` | 120 |
| `guidance` | 1,000 |

* **An `app.*` type takes no guidance.** An empty string is none.
* **Adding, changing or removing guidance needs `schema.write`,** or Marfa answers `403 forbidden`. An app's sign-in, a key an app made and a key of unknown maker are refused even with it: the owner writes guidance, directly or through a [plugin](/use/install-a-plugin).
* **`GET /types/{id}` adds `ancestor_guidance`,** the guidance of each type above, nearest first.
* **Text stored over a limit** reads as it is, until a replacement brings it within.

## Fields [#fields]

A field can't take a name every item has: Marfa refuses it with `400 property_shadows_field`.

`capture_latitude`, `capture_longitude`, `created_at`, `id`, `last_activity_at`, `occurred_at`, `properties`, `read_only`, `schema_version`, `source`, `source_id`, `state`, `tier`, `trashed_at`, `trashed_by_cascade`, `trashed_with`, `type`, `updated_at`, `version`

## Parent and inheritance [#parent-and-inheritance]

| Rule | Marfa allows or refuses |
| - | - |
| `parent` | Names a registered type, with no loop and at most ten ancestors. Refused `400 validation_error`. |
| A subtype may | Add fields, redeclare an inherited field or give it a new `description` or `label`, make it required, add or narrow a range on an inherited `number` or `integer`, and add status words. |
| A subtype may not | Change an inherited field's `type`, `format`, `items_type`, `items_fields`, `searchable`, `max_length`, `max_items` or `enum_values`, widen or drop its range, or make a required field optional. Refused `400 inheritance_violation`, naming the field. |
| Write access | A new `parent` that Marfa doesn't ship needs write on it. Keeping one doesn't. Refused `403 type_not_permitted`. |

**Only `parent` makes a type's items readable as another type.** A parent change that breaks a subtype is refused too. [Upgrade](/run/upgrade#types-a-new-build-leaves-in-conflict) covers a shipped type that gains a field a subtype declares in another shape.

## Display hints [#display-hints]

`display_hints` takes four optional hints. Marfa refuses a bad one with `400 invalid_schema`, naming the member.

| Hint | What it holds | Marfa refuses |
| - | - | - |
| `title_field` | The field that names an item. | A field the type and its ancestors don't declare, or a `thumbnail` field. |
| `body_field` | The field that holds the item's text, in Markdown, stored as sent. | The same as `title_field`. |
| `name_from_body` | `false` where the text never names an item, as on `core.highlight`. Unset, it can. | Anything but `true` or `false`. |
| `icon` | An [Iconify](https://iconify.design/) icon ID, `<set>:<name>`, from `lucide` or, for brand marks, `simple-icons`, such as `lucide:star`. | A bare name, another set, a name the set's pinned version lacks, an alias, a hidden icon, or a wrong-case or padded ID. |

* **Each hint comes from the nearest type that sets it.**
* **The accepted icons** are in [`icon-set-lucide.json`](https://github.com/withmarfa/marfa/blob/v0.0.90/core/marfa-rules/icons/icon-set-lucide.json) and [`icon-set-simple-icons.json`](https://github.com/withmarfa/marfa/blob/v0.0.90/core/marfa-rules/icons/icon-set-simple-icons.json).
* **An item is named** from its title fields, then a host or excerpt source it is part of, then its other text fields, and is `Untitled` when none holds text. [`types/item-name-fields`](https://github.com/withmarfa/marfa/blob/v0.0.90/conformance/spec/types.md#typesitem-name-fields) gives the order.

### The owner's icon [#the-owners-icon]

`marfa types set-icon` and `clear-icon` set the owner's icon on any type, over the author's and kept through a replacement.

## Roles [#roles]

`roles` takes `container` alone. A `container` type can be the to item of an [`in-collection`](/catalog/edges/in-collection) edge and never its from item (`400 edge_constraint_violation`).

[List types](/reference/api/types/listTypes) answers `roles`, all a type plays, and `own_roles`, those it declares. **When you [replace a type](/reference/api/types/replaceType), send its `own_roles` as `roles`.**

## Link field [#link-field]

`link_field` names a `string` field that holds each item's own ID at the vendor that writes the type. A [connector](/build/connector-push#send-a-new-item-to-the-vendor) finds an item by it.

* **The value is unique within the type,** in every state. A write that gives it to a second item is refused `409 link_taken`, and `details.existing_id` names the holder. An empty value is no link.
* **A field that isn't a declared or inherited `string`,** or whose name holds `"` or `\`, is refused `400 invalid_schema`.
* **A subtype inherits the field, not the link.**

## Merge policy [#merge-policy]

`merge_policy` maps a field to a strategy, and `default` covers the rest. Left out, `default` is the parent's, and `last_writer_wins` where no type above names one. They settle a collision when a write asks for `conflict=auto` ([`versions/auto-keep-both`](https://github.com/withmarfa/marfa/blob/v0.0.90/conformance/spec/versions.md#versionsauto-keep-both)).

| Strategy | When a later write collides with another on the field |
| - | - |
| `last_writer_wins` | The item takes the later writer's value. |
| `keep_both_copies` | The item keeps its value, and the later writer's value goes to a new item tagged `conflicted-copy`. |

## Version policy [#version-policy]

`version_policy` sets how long Marfa keeps an item's earlier versions. The `version-thinning` [housekeeping job](/run/check-health) removes the rest, except from an item with two snapshots or fewer ([`housekeeping/thinning-minimum`](https://github.com/withmarfa/marfa/blob/v0.0.90/conformance/spec/housekeeping.md#housekeepingthinning-minimum)). The daily and weekly windows keep the latest snapshot of each UTC day or ISO week ([`housekeeping/thinning-daily`](https://github.com/withmarfa/marfa/blob/v0.0.90/conformance/spec/housekeeping.md#housekeepingthinning-daily)).

| Key | Marfa keeps |
| - | - |
| `recent_days` | Every version, back this many days. |
| `daily_snapshot_days` | One a day, back this many days. |
| `weekly_snapshot_days` | One a week, back this many days. 0 removes none for its age. |
| `max_versions` | At most this many, dropping the oldest first. |

A window is a whole number from 0 to 36500 and `max_versions` one from 1 to 1,000,000. A window that ends sooner than the one above it, among those the definition declares, is refused `400 invalid_schema`. **Marfa always keeps the newest version.** A key left out comes from the parent type, then the instance's defaults.

## Retention policy [#retention-policy]

`retention_policy` takes only `feed_days`:

| `feed_days` | Effect |
| - | - |
| 1 to 36500 | The `feed-expiry` [housekeeping job](/run/check-health) moves the type's active feed items to the bin more than that many days after their `created_at`. An archived item, and one restored from the bin, stays ([`housekeeping/feed-expiry-archived`](https://github.com/withmarfa/marfa/blob/v0.0.90/conformance/spec/housekeeping.md#housekeepingfeed-expiry-archived)). |
| `null` | The type keeps its feed items, whatever a parent sets. |
| Left out | The type takes its parent's window. |

The rules behind this page are in the [types](https://github.com/withmarfa/marfa/blob/main/conformance/spec/types.md), [items](https://github.com/withmarfa/marfa/blob/main/conformance/spec/items.md), [versions](https://github.com/withmarfa/marfa/blob/main/conformance/spec/versions.md), [edges](https://github.com/withmarfa/marfa/blob/main/conformance/spec/edges.md), [housekeeping](https://github.com/withmarfa/marfa/blob/main/conformance/spec/housekeeping.md) and [device](https://github.com/withmarfa/marfa/blob/main/conformance/spec/device.md) chapters of the contract.
