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 registers one, and Field kinds holds the rules for fields and tables. marfa types check applies them before you register.
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. 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. |
tables | An object of tables by name. |
label, plural | See Label and plural. |
parent | See 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
- 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 inapp.readinglist.entry. Anything else is400 validation_error. core,systemandmarfa: refused403 forbidden, whatever the credential.common: a new type is refused403 forbiddennamingmarfa plugins install, since only a plugin adds one.- An
app.<vendor>someone else holds: refused403 forbidden(Access). - Other reserved roots: every root below except
app,user,common,core,systemandmarfais refused400 validation_error. A root is the whole first segment, socore-pubis 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
Each is optional and at most 100 characters.
labelnames one item, such asRecipe. Left out, Marfa makes it from the identifier's last segment:user.reading-listisReading List.pluralnames a list, such asRecipes. Left out, Marfa makes it by the regular English rule, soStorymakesStories. Declare it where that is wrong, as inPeople.
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 answers403 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. GET /types/{id}addsancestor_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
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
| 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 covers a shipped type that gains a field a subtype declares in another shape.
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 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.jsonandicon-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
Untitledwhen none holds text.types/item-name-fieldsgives the order.
The owner's 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 takes container alone. A container type can be the to item of an in-collection edge and never its from item (400 edge_constraint_violation).
List types answers roles, all a type plays, and own_roles, those it declares. When you replace a type, send its own_roles as roles.
Link field
link_field names a string field that holds each item's own ID at the vendor that writes the type. A connector 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, anddetails.existing_idnames the holder. An empty value is no link. - A field that isn't a declared or inherited
string, or whose name holds"or\, is refused400 invalid_schema. - A subtype inherits the field, not the link.
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).
| 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 sets how long Marfa keeps an item's earlier versions. The version-thinning housekeeping job removes the rest, except from an item with two snapshots or fewer (housekeeping/thinning-minimum). The daily and weekly windows keep the latest snapshot of each UTC day or ISO week (housekeeping/thinning-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 takes only feed_days:
feed_days | Effect |
|---|---|
| 1 to 36500 | The feed-expiry housekeeping job 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). |
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, items, versions, edges, housekeeping and device chapters of the contract.