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.

KeyRule
idRequired to register. See Identifier. An otherwise valid, permitted registration of one already registered is refused 409 type_exists.
fieldsRequired, an object of field definitions. Refused 400 missing_required_field when missing.
requiredA list of field names the type or an ancestor declares, the same as required: true on each.
versionA whole number of 0 or more that Marfa never changes. Defaults to 0.
description, guidanceSee Descriptions and guidance.
tablesAn object of tables by name.
label, pluralSee Label and plural.
parentSee Parent and inheritance.
display_hints, roles, link_fieldSee the sections of the same name.
merge_policy, version_policy, retention_policySee 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 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 adds one.
  • An app.<vendor> someone else holds: refused 403 forbidden (Access).
  • 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

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

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:

TextAt most
A type's description200
A field's or an items_fields member's description300
A status word's description120
guidance1,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.
  • 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

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

RuleMarfa allows or refuses
parentNames a registered type, with no loop and at most ten ancestors. Refused 400 validation_error.
A subtype mayAdd 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 notChange 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 accessA 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.

HintWhat it holdsMarfa refuses
title_fieldThe field that names an item.A field the type and its ancestors don't declare, or a thumbnail field.
body_fieldThe field that holds the item's text, in Markdown, stored as sent.The same as title_field.
name_from_bodyfalse where the text never names an item, as on core.highlight. Unset, it can.Anything but true or false.
iconAn 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.

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 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, 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 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).

StrategyWhen a later write collides with another on the field
last_writer_winsThe item takes the later writer's value.
keep_both_copiesThe 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).

KeyMarfa keeps
recent_daysEvery version, back this many days.
daily_snapshot_daysOne a day, back this many days.
weekly_snapshot_daysOne a week, back this many days. 0 removes none for its age.
max_versionsAt 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_daysEffect
1 to 36500The 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).
nullThe type keeps its feed items, whatever a parent sets.
Left outThe 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.

On this page