Entity Reference

Define entities with defineEntity().

import { defineEntity } from '@flexkit/schema';
 
export const customers = defineEntity({
  name: 'customer',
  plural: 'customers',
  display: 'name',
  menu: {
    label: 'Customers',
    group: 'sales',
    icon: 'Users',
  },
  attributes: [
    {
      name: 'name',
      label: 'Name',
      scope: 'global',
      dataType: 'string',
      inputType: 'text',
      defaultValue: '',
    },
  ],
});

Entity Shape

name: string singular identifier (example: customer).
plural: string plural collection name (example: customers).
display?: string attribute name shown in relationship previews, search hits, and edit-drawer titles. Must match an attribute name. Falls back to the first attribute when omitted. The effective display attribute cannot be space-bound.
menu?: { hidden?: boolean; label?: string; group?: string; icon?: string } sidebar placement. See Menu Behavior.
spaces?: string[] permission space codes that can access the entity. See Permission spaces.
groups?: FieldGroup[] form tabs. Distinct from menu.group (sidebar section). See Field Groups.
attributes: Attribute[] list of field definitions.

Naming Guidelines

Use singular name values for entity types (product, not products).
Use alphanumeric or underscore names for compatibility.
Keep names stable: changing names impacts queries, references, and migrations.
Avoid reserved/system-like names for fields and entities when possible.

menu.label controls the sidebar label.
menu.group maps to a project menuGroups[].name. The group must be declared in menuGroups, or the deploy is rejected.
menu.icon is a lucide icon name in PascalCase, such as 'Tag' or 'ShoppingCart'. When omitted, Studio uses the icon whose name equals the entity name (singular or plural, such as language → Languages) and otherwise a neutral default, so set menu.icon for anything else. React elements are not accepted.
menu.hidden: true excludes the entity from the sidebar while keeping it in the schema.

Field Groups

groups organizes the edit form into tabs. It does not change storage.
Each group is { name: string; title?: string; icon?: string; default?: boolean; hidden?: boolean }. icon is a lucide icon name, as for menu.icon; hidden is a plain boolean.
Assign attributes with group: 'seo' or group: ['seo', 'media'].
Studio always adds an All fields tab. Hide it with { name: 'all', hidden: true } in groups. Attributes with no visible tab are omitted from the form and validation.

Entity Design Tips

Keep entity boundaries business-centric (Catalog, CRM, ERP, etc.).
Set display to one attribute name for predictable relationship labels.
Normalize shared concepts into separate entities (currency, country, tag, supplier).
Model cross-entity workflows via relationships, not duplicated text fields.

Permission spaces

Use spaces: ['catalog'] to restrict a supported entity or global/local attribute to members of a deployed space. Membership in any listed space is sufficient. The effective display attribute cannot be space-bound, and relationship-scoped attributes cannot declare spaces. See permission spaces for deployment and assignment.