The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
---
title: Overview
description: Shape the data your app adds to a workspace — objects, fields, and relations.
---
import { PageBanner } from "/snippets/page-banner.mdx"
import { CardTitle } from "/snippets/card-title.mdx"
## What the data layer covers
A Twenty app's **data layer** is the data your app *adds* to a workspace — the new record types it declares, the columns it adds to existing objects, and how those records connect to each other.
```text
┌──────────────────────────────────────────────────┐
│ Object — a record type, e.g. PostCard │
│ ├─ Field (name, type, label) │
│ ├─ Field │
│ └─ Relation (link to another object) │
└──────────────────────────────────────────────────┘
│
├── lives in your app, OR
│
▼
┌──────────────────────────────────────────────────┐
│ Standard / other apps' objects │
│ └─ Field added by your app via defineField │
└──────────────────────────────────────────────────┘
```
## In this section
<CardGroup cols={2} className="documentation-card-group">
<Card href="/developers/extend/apps/data/objects" img="/images/user-guide/halftone/card-page-objects.svg">
<CardTitle>Objects</CardTitle>
`defineObject` — declare new record types with their own fields.
</Card>
<Card href="/developers/extend/apps/data/extending-objects" img="/images/user-guide/halftone/card-page-extending-objects.svg">
<CardTitle>Extending Objects</CardTitle>
`defineField` — add fields to standard or other apps' objects.
</Card>
<Card href="/developers/extend/apps/data/relations" img="/images/user-guide/halftone/card-page-relations.svg">
<CardTitle>Relations</CardTitle>
Bidirectional `MANY_TO_ONE` / `ONE_TO_MANY` connections between objects.
</Card>
<Card href="/developers/extend/apps/data/timeline-activity-types" img="/images/user-guide/halftone/card-page-timeline.svg">
<CardTitle>Timeline Activity Types</CardTitle>
Define automatic audit events and explicit app events for record timelines.
</Card>
<Card href="/developers/extend/apps/data/validation-rules" img="/images/user-guide/halftone/card-page-objects.svg">
<CardTitle>Validation Rules</CardTitle>
`defineValidationRule` — declare the conditions a record must meet before it can be saved.
</Card>
</CardGroup>
## Entities at a glance
| Entity | Purpose | Defined with |
|--------|---------|--------------|
| **Object** | A new custom record type (e.g. PostCard, Invoice) with its own fields | `defineObject()` |
| **Field** | A column on an object. Standalone fields can extend objects you didn't create (e.g. add `loyaltyTier` to Company) | `defineField()` |
| **Relation** | A bidirectional link between two objects — both sides declared as fields | `defineField()` with `FieldType.RELATION` |
| **Index** | A database index to speed up a recurring query on one of your objects | `defineIndex()` |
| **Timeline activity type** | An automatic audit event or explicit domain event shown in record timelines | `defineTimelineActivityType()` |
| **Related record path** | A chain of up to three relations along which access to a record extends to its related records | `defineRelatedRecordPath()` |
| **Validation rule** | A condition a record must meet before it can be saved | `defineValidationRule()` |
The CLI detects these via AST analysis at build time, so file organization is up to you — the convention is `src/objects/`, `src/validation-rules/`, `src/fields/`, `src/indexes/`, `src/timeline-activity-types/`, and `src/related-record-paths/`. Stable `universalIdentifier` UUIDs tie everything together across deploys.
## Indexes (optional)
Apps can ship indexes alongside their objects to keep recurring queries fast. The most common case is a status or foreign-key column that you read frequently.
```ts src/indexes/post-card-status.index.ts
import { defineIndex } from 'twenty-sdk/define';
import {
POST_CARD_UNIVERSAL_IDENTIFIER,
STATUS_FIELD_UNIVERSAL_IDENTIFIER,
} from '../objects/post-card.object';
export default defineIndex({
universalIdentifier: 'b6e9d2a1-5a4c-46ca-9d52-42c8f02d1ff0',
objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
fields: [
{
universalIdentifier: 'b6e9d2a1-5a4c-46ca-9d52-42c8f02d1ff1',
fieldUniversalIdentifier: STATUS_FIELD_UNIVERSAL_IDENTIFIER,
},
],
});
```
### Unique indexes
`defineIndex` accepts `isUnique: true` for both single- and multi-column uniqueness. This is the recommended primitive — `defineField({ isUnique: true })` is deprecated and will be removed in a future release.
```ts
defineIndex({
universalIdentifier: '…',
objectUniversalIdentifier: PERSON_UNIVERSAL_IDENTIFIER,
isUnique: true,
fields: [{ universalIdentifier: '…', fieldUniversalIdentifier: EMAIL_FIELD_UNIVERSAL_IDENTIFIER }],
});
```
### Other constraints
- Partial `WHERE` clauses stay under admin control — apps can't declare them.
- Each object is capped at 10 custom indexes (the framework's own indexes don't count).
Order the `fields` array the way Postgres should use it — leftmost column first, like a phone book. Indexes are not free: every write to the table updates them. Add one only when you have a query that needs it.
## Related record paths (optional)
<Warning>
Related record paths are in preview: they sync with your app, but record
permissions don't use them yet. Once enforced, they require the
**Organization plan or above**, like
[row-level security](/developers/extend/apps/config/roles#row-level-security).
</Warning>
A related record path starts on an object and follows up to three relation fields, each on the object the previous one reached. Record permissions use these paths to extend access from a record to its related records.
- An **inherent** path (`isInherent: true`) applies whenever the starting record is readable, however that access was granted. Use it for records that belong to their parent, such as a post card's attachments.
- A **regular** path applies only when access to the starting record comes directly from a role, so workspaces choose which ones to rely on.
```ts src/related-record-paths/post-card-attachments.related-record-path.ts
import { defineRelatedRecordPath } from 'twenty-sdk/define';
import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
import { ATTACHMENTS_ON_POST_CARD_UNIVERSAL_IDENTIFIER } from '../fields/attachments-on-post-card.field';
export default defineRelatedRecordPath({
universalIdentifier: 'c1b8f0d2-7e4a-4b6c-9a1d-3f5e2b7c8d90',
objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
firstFieldMetadataUniversalIdentifier:
ATTACHMENTS_ON_POST_CARD_UNIVERSAL_IDENTIFIER,
isInherent: true,
});
```
Add `secondFieldMetadataUniversalIdentifier` and `thirdFieldMetadataUniversalIdentifier` for longer paths. Each hop must be an active relation on the object reached so far, a path can't visit the same object twice, and two paths can't use the same hops.
<Note>
Looking for **Application Config** or **Roles & Permissions**? Those describe the app itself rather than the data it adds — they live under [Config](/developers/extend/apps/config/overview). Looking for **Connections** (Linear, GitHub, Slack OAuth)? Those exist to be called *from* logic functions and live under [Logic](/developers/extend/apps/logic/connections).
</Note>
<PageBanner illustration="section-apps-data" />