Extending Objects

Use defineField() to add a field to an object you don’t own — a standard Twenty object like Person or Company, or an object shipped by another installed app. Unlike inline fields declared inside defineObject, standalone fields require an objectUniversalIdentifier to specify which object they extend.

src/fields/company-loyalty-tier.field.ts

import { defineField, FieldType } from 'twenty-sdk/define';

export default defineField({
  universalIdentifier: 'f2a1b3c4-d5e6-7890-abcd-ef1234567890',
  objectUniversalIdentifier: '701aecb9-eb1c-4d84-9d94-b954b231b64b', // Company object
  name: 'loyaltyTier',
  type: FieldType.SELECT,
  label: 'Loyalty Tier',
  icon: 'IconStar',
  options: [
    { value: 'BRONZE', label: 'Bronze', position: 0, color: 'orange' },
    { value: 'SILVER', label: 'Silver', position: 1, color: 'gray' },
    { value: 'GOLD', label: 'Gold', position: 2, color: 'yellow' },
  ],
});

Key points

objectUniversalIdentifier identifies the target object. For standard Twenty objects, import the constant from twenty-sdk:

import { STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define';

// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier
// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier
// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.opportunity.universalIdentifier
// …

When defining fields inline inside defineObject(), you do not need objectUniversalIdentifier — it’s inherited from the parent object.
defineField() is the only way to add fields to objects you didn’t create with defineObject().
SELECT and MULTI_SELECT follow the same option validation and color rules as inline fields. An omitted or null color defaults to gray; unsupported colors are rejected.
File location is up to you. The convention is src/fields/<name>.field.ts, but the SDK detects fields anywhere in src/.
writability can also be set per field: MetadataWritability.APPLICATION restricts writes to your app’s own logic functions, MetadataWritability.SYSTEM is reserved for platform-managed data. A field’s writability can only be stricter than its object’s level, and reads are unaffected. See Objects for the full semantics.
isSearchable: true can be set on defineField() with the same constraints as inline fields (searchable target object, text-compatible field type), so records of the target object become findable through your field’s values in full-text search.
isAuditLogged: false can be set on defineField() to keep the field’s changes out of the target record’s timeline, which matters most for fields your app rewrites on a schedule.
To add a tab to a standard page layout (e.g. the Task or Company detail page), use definePageLayoutTab with STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS from twenty-sdk/define.

Adding a relation to an existing object

To add a relation field (e.g. linking your custom object to a standard Person), use defineField() with FieldType.RELATION. The pattern is the same as for inline relations but with objectUniversalIdentifier set explicitly. See Relations for the bidirectional pattern.

Overview

Apps

API

Self-Host

Contribute

UI Library

Key points

Adding a relation to an existing object

​Key points

​Adding a relation to an existing object

Key points

Adding a relation to an existing object