Metadata Engine & Dynamic Objects
Relevant source files
The following files were used as context for generating this wiki page:
- packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md
- packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/skill-metadata/create-standard-flat-skill-metadata.util.ts
- packages/twenty-codex-plugin/references/publish-app/prepare-for-app-store.md
- packages/twenty-claude-skills/skills/twenty-record-presentation/SKILL.md
- CLAUDE.md
- packages/twenty-codex-plugin/AGENTS.md
The Metadata Engine is the core architectural component of Twenty that enables a fully modular and customizable data model. It allows the system to distinguish between standard objects (built-in entities) and custom objects created to satisfy specific domain requirements. By managing object definitions, field types, and relationships as metadata, the engine supports dynamic schema evolution without requiring structural code rewrites.
Dynamic objects and their associated metadata drive the user interface, permissions, and automation layers. This system ensures that every entity—whether it is a standard Person or a custom Property—is treated with a consistent set of capabilities, including attachment support, notes, tasks, and timeline tracking.
Sources: packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md:46-51, packages/twenty-website/src/app/[locale]/customers/netzero/page.tsx:75-78
Core Data Model Architecture
The metadata engine maintains a strict separation between core system data and workspace-specific schema definitions. The multi-tenant schema structure is organized into core, metadata, and workspace-specific schemas.
Object Classification
Twenty categorizes entities into two primary groups:
- Standard Objects: Built-in entities provided by the platform (e.g.,
Company,Person,Opportunity,Task,Note). - Custom Objects: Domain-specific entities created by users or apps (e.g.,
Project,Product,Repair).
Sources: packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/skill-metadata/create-standard-flat-skill-metadata.util.ts:161-167, CLAUDE.md:79-84
Data Flow for Metadata Operations
The following diagram illustrates the flow of creating and synchronizing metadata entities within the engine.
The engine uses CLI tools like twenty dev:add to generate metadata definitions, which are then synchronized to the database to update the workspace schema and regenerate the GraphQL API.
Sources: packages/twenty-codex-plugin/AGENTS.md:63-65, CLAUDE.md:86-88
Metadata Definitions and Field Types
The engine supports a wide array of field types, each with specific validation rules and rendering logic. Metadata for objects and fields includes labels, internal names, descriptions, and icons.
Supported Field Types
| Field Type | Description |
|---|---|
| TEXT / RICH_TEXT | Simple string values or formatted content. |
| NUMBER / NUMERIC | Integers or decimals for calculations. |
| CURRENCY | Monetary values with currency code support. |
| DATE / DATE_TIME | Temporal data used for calendars and timelines. |
| SELECT / MULTI_SELECT | Single or multiple choice options (UPPER_SNAKE_CASE). |
| RELATION | Links between objects (MANY_TO_ONE, ONE_TO_MANY). |
| BOOLEAN | True/false values. |
| EMAILS / PHONES / LINKS | Specialized types for contact and web data. |
Sources: packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/skill-metadata/create-standard-flat-skill-metadata.util.ts:400-418, packages/twenty-claude-skills/skills/twenty-record-presentation/SKILL.md:68-84
Composite and Relation Fields
The engine handles complex fields by exposing sub-fields. For instance, a CURRENCY field exposes amountMicros, while a FULL_NAME field exposes firstName and lastName. Relation fields (including MORPH_RELATION) require a subFieldName to determine which scalar field from the target object should be displayed or grouped.
Relationship Modeling
Relationships are a first-class citizen in the metadata engine. The system supports MANY_TO_ONE and ONE_TO_MANY relationship types, which define how data flows between different objects.
Relationships carry significant "scoping signal" for the platform, such as ownership tracking and parent/child hierarchies.
Sources: packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md:50-54, packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/skill-metadata/create-standard-flat-skill-metadata.util.ts:223-231
Metadata Management Tools
The platform provides internal utilities and API endpoints to interact with the Metadata Engine.
Key Metadata Utilities
get_object_metadata: Retrieves definitions for all objects. Standard objects can be returned in a compact format (id,nameSingular) or full configuration.get_field_metadata: Lists all fields for a specific object, excluding internal fields likesearchVectororupdatedBy.create_many_object_metadata: Batch creation of custom objects to minimize backend side effects.update_many_object_metadata: Batch updates, often used for archiving custom objects by settingisActivetofalse.
Sources: packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/skill-metadata/create-standard-flat-skill-metadata.util.ts:200-210, packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/skill-metadata/create-standard-flat-skill-metadata.util.ts:390-398
Lifecycle of Dynamic Objects
- Declaration: Metadata is defined via
defineApplication()or the CLI. - Validation: The engine validates field names (camelCase) and select options (UPPER_SNAKE_CASE).
- Persistence: Definitions are stored in metadata tables.
- Activation: Schema changes are applied to the database, making the object available for records.
- Cleanup: Objects can be archived, which hides them from the UI without deleting the underlying data.
Sources: packages/twenty-codex-plugin/references/publish-app/prepare-for-app-store.md:120-138, packages/twenty-server/src/engine/workspace-manager/twenty-standard-application/utils/skill-metadata/create-standard-flat-skill-metadata.util.ts:600-610
Conclusion
The Metadata Engine and Dynamic Objects system provides the foundation for Twenty's extensibility. By treating the data model as a configurable layer rather than a static codebase, it enables rapid prototyping and domain-specific customization. This architecture ensures that standard CRM features remain stable while allowing users to build complex, relational data structures that grow with their business needs.