Skip to main content
Custom objects are new record types your app adds to a workspace — Post Card, Invoice, Subscription, anything specific to your domain. Each object declares its schema (fields, relations, default values) and a stable universal identifier that survives across syncs and deploys.
src/objects/post-card.object.ts

​
Key points

  • The universalIdentifier must be unique and stable across deployments.
  • Each field requires a name, type, label, and its own stable universalIdentifier.
  • The fields array is optional — you can define objects without custom fields.
  • openRecordIn sets where records of this object open when clicked: ObjectOpenRecordIn.USER_CHOICE (the default, following each workspace member’s own preference from Settings → Experience), ObjectOpenRecordIn.SIDE_PANEL, or ObjectOpenRecordIn.RECORD_PAGE. Pin it to RECORD_PAGE for records that need a full page to be usable, the way workflows and dashboards do, or to SIDE_PANEL for records that only make sense as a quick panel, the way calendar events do.
  • writability controls who may write records of the object at all, before role permissions apply: MetadataWritability.OPEN (the default — workspace roles decide), MetadataWritability.APPLICATION (only your app’s own logic functions can create, update, or delete records; use this for configuration-like objects whose records grant behavior, so workspace members with broad record access cannot edit them through the API), or MetadataWritability.SYSTEM (reserved for platform-managed data). Reads are unaffected — this is enforced server-side, unlike isUIEditable, which only hides UI affordances. It also exists per field, where it can only be stricter than the object’s level.
  • readability declares who may read records of the object: MetadataReadability.OPEN (the default — workspace roles decide), MetadataReadability.PRIVATE (only principals the record was shared with), MetadataReadability.INHERITED (whoever reads the parent record), MetadataReadability.APPLICATION (only your app’s own logic functions) or MetadataReadability.SYSTEM (platform-managed data). SYSTEM is always enforced. PRIVATE, INHERITED and APPLICATION are enforced on workspaces where record sharing is enabled (IS_RECORD_SHARING_ENABLED); elsewhere they still behave like OPEN.
  • readabilityParentFieldUniversalIdentifiers goes with MetadataReadability.INHERITED: the universal identifiers of the relation fields that lead to the parent records.
    • A many-to-one field names the record the row points to. Declaring one field of a morph relation covers every target of that relation.
    • A one-to-many field names a child object whose rows point back at the record, such as the join rows of a many-to-many relation. The record is then readable when at least one of those rows leads to a readable record: a note follows the people, companies and opportunities its note targets attach it to.
    • Several parents combine as a union: one readable parent is enough.
    • A parent grants access under its complete policy, the one a query of the parent applies: the reader’s permission on the parent object, the row-level restrictions of their role and the parent’s own readability. A record never shows through a parent its reader could not query. Subscriptions, webhooks, workflows and logic functions decide what an event of an INHERITED record reaches by that same policy.
    • The share rows on the record itself grant access exactly as on a PRIVATE record. Its creator gets one when the record is created while record sharing is enabled, so whoever created a record keeps seeing it, and a record whose parent fields are all empty is visible to those it was shared with directly.
    • An INHERITED object that names no usable parent field behaves like a PRIVATE one.
  • color sets the accent color of the object in the UI. Omit it and Twenty picks one for the object.
  • imageIdentifierFieldMetadataUniversalIdentifier names the field whose value is shown as the record avatar. Omit it to let Twenty pick the default.
  • isLabelSyncedWithName, on an object or on a field, keeps the API name in sync with the label when the label is edited in Settings. It defaults to false, so a renamed label leaves the name untouched.
  • isSearchable: true, on a field, includes its values in the object’s full-text search (global search and the command menu). It requires the object itself to be searchable and a text-compatible field type. An omitted value means not searchable, except for the object’s label identifier field, which is always searchable and cannot be opted out. Each sync enforces the declared state, so a field toggled searchable from Settings reverts on your app’s next sync unless the manifest declares it.
  • isAuditLogged: false, on a field, keeps its changes out of the record timeline. It defaults to true, except on a POSITION field, whose changes render blank in the timeline and are never logged. Set it on fields your app rewrites on a schedule, such as a last-contact timestamp or a rollup relation, so each sync does not add an activity row to every record it touches. An update whose whole diff is made of non audit logged fields produces no timeline activity at all. Like isSearchable, each sync enforces the declared state.
  • Inline fields defined here do not need an objectUniversalIdentifier — it’s inherited from the parent object. Use defineField() to add fields to objects you don’t own.
  • You can scaffold new objects with yarn twenty dev:add object, which guides you through naming, fields, and relationships. See Architecture → Scaffolding entities.
Base fields are added automatically. When you define a custom object, Twenty creates standard fields like id, name, createdAt, updatedAt, createdBy, updatedBy, and deletedAt for you. You don’t need to declare them in your fields array — only your custom fields. You can override a default field by declaring one with the same name, but this is rarely a good idea.

​
Field types

The full set of FieldType values, exported from twenty-sdk/define: Composite types store multiple sub-fields (e.g. FULL_NAME = first + last name; CURRENCY = amountMicros + currencyCode). SELECT and MULTI_SELECT require an options array as in the example above.

​
Select options

For SELECT and MULTI_SELECT, provide a non-empty options array of objects. Each option has a value, label, and position. Its color is optional and defaults to gray when omitted or null. When provided, color must be one of: red, ruby, crimson, tomato, orange, amber, yellow, lime, grass, green, jade, mint, turquoise, cyan, sky, blue, iris, violet, purple, plum, pink, bronze, gold, brown, gray. Both defineObject() and defineField() return validation errors for unsupported colors or option entries that are null, primitives, or arrays.

​
Default values

Literal string defaults must be wrapped in single quotes inside the string — defaultValue: "'Draft'", not defaultValue: "Draft". That’s why the status field above uses `'${PostCardStatus.DRAFT}'`. Unquoted strings are reserved for computed defaults, evaluated when a record is created:
  • 'uuid' — generates a UUID (for UUID fields)
  • 'now' — the current timestamp (for DATE_TIME fields)
The same convention applies to string sub-fields of composite defaults (e.g. { source: "'MANUAL'" } on an ACTOR field) and to SELECT/MULTI_SELECT values. A literal string default left unquoted raises a warning when your app is built.

​
Nullability

isNullable controls whether a field accepts NULL. It defaults to true — omit it for optional fields. Set isNullable: false to make a field required at the database level. Changes to isNullable are applied on every sync, including syncs that update an existing field — so you can flip a field’s nullability by editing the manifest and re-syncing.
Making an existing field non-nullable requires a default value. When you change a field to isNullable: false, you must also provide a non-null defaultValue. The default backfills any existing NULL rows before the NOT NULL constraint is applied; without it the sync fails with Default value cannot be null for non-nullable fields. Relation fields and TS_VECTOR fields are always nullable, so isNullable has no effect on them.

​
What’s next

  • Connect this object to others — see Relations for the bidirectional relation pattern.
  • Add fields to objects from other apps — see Extending Objects for defineField().
  • Display this object in the UI — see Navigation Menu Items to add a sidebar entry; see Views to add custom list configurations.