Metadata model

Every module describes its screens with metadata: Pydantic objects defined in src/cluster_erp/core/metadata.py. This page lists those classes and their main fields as the server-side contract. How the web app renders them is documented on metadata rendering; the desktop client is documented in the desktop section.

Scope and source¶

• Defined in: src/cluster_erp/core/metadata.py
• Count: 45 classes (counted with grep -c "^class "), plus the alias LabelDict = dict[str, str] (src/cluster_erp/core/metadata.py:7). 186 calls of EntityMeta( exist under src/cluster_erp (counted with grep -rn "EntityMeta(").

LabelDict maps a language code to a text, for example {"en": "...", "tr": "..."}. Every label, placeholder, help text, and description in the metadata uses it.

How metadata is served¶

A module returns its ModuleMeta from get_metadata() (src/cluster_erp/core/module_base.py:73-74). GET /api/v1/_meta serialises every loaded module's metadata with model_dump(exclude_none=True) after the tenant-field entities are added, into one JSON document {"version": "1.0", "modules": {...}}. The document is built once per process and served with an ETag and a gzip form, and only to a signed-in caller (src/cluster_erp/server/app.py:1518-1556). A field whose value is None is therefore absent from the document.

Module and entity¶

EntityMeta checks at construction that the form tabs of its detail view cover every form group that is not create_only, and that they name no unknown group. A mismatch raises ValueError when the module is imported (src/cluster_erp/core/metadata.py:617-649).

Forms and fields¶

FieldMeta.field_type takes one of 19 values: string, text, integer, float, decimal, boolean, date, datetime, enum, multi_enum, foreign_key, multi_foreign_key, json, hidden_scope_field, file_upload, suggest_combo, dynamic_form, field_list, and string_list (src/cluster_erp/core/metadata.py:82-102). FieldMeta.permission hides a field's value from callers without that permission code; the comment names core/field_access.py as the enforcing code (src/cluster_erp/core/metadata.py:115-119). FieldMeta.switch shows a field only while a tenant display switch is on (src/cluster_erp/core/metadata.py:120-125). FieldMeta.storage is column for shipped fields and extra for tenant-defined fields (src/cluster_erp/core/metadata.py:142-146).

Lists¶

ColumnMeta.formatter takes one of boolean, active_flag, date, datetime, decimal, enum, foreign_key, entity_type, entity_record, or i18n_message (src/cluster_erp/core/metadata.py:190-212).

Detail views¶

DetailTabMeta.tab_type takes one of form, custom, sub_entity_table, sub_entity_tree, permission_checklist, role_checklist, access_summary, completeness, or read_model_panel (src/cluster_erp/core/metadata.py:255-270). The RecordLockMeta docstring requires values to come from the same constant that the service enforces (src/cluster_erp/core/metadata.py:486-488).

Parties, facets, and composite creation¶

These classes implement the party unification rule of the project's written engineering rules. See party unification.

Actions and links¶

ActionMeta.scope is one of global, single_record, or parent (src/cluster_erp/core/metadata.py:422). See actions and action sheet.

Trees, sidebar, and home¶

SidebarSectionMeta.view_type is one of list, detail, tree, settings, custom, or tabbed_list (src/cluster_erp/core/metadata.py:667). HomeWidgetMeta.size must match the pattern NxM (src/cluster_erp/core/metadata.py:710).

Tenant fields¶

See tenant fields.

Constraints and validation¶

• Metadata objects are Pydantic models; a wrong literal value or a missing required field fails when the module builds its metadata.
• At start-up the server fails if a sub_entity_table tab points at an entity without columns (src/cluster_erp/server/app.py:547-589).
• The project's written engineering rules make the web app fully metadata-driven: screen, form, list, and action behaviour comes from metadata. tests/test_metadata_driven_rules.py and tests/test_architecture_boundaries.py:75 guard parts of this rule; see architecture boundaries.

Terms introduced¶

Related pages¶

• Platform core
• Metadata rendering
• Tenant fields
• Module lifecycle
• Metadata-driven UI

Verified against commit 92f8051 on 2026-11-13.