Collections Design

Collections Design

Expert guidance on designing NocoBase collections (data models) — types, naming, system fields, inheritance, and architecture patterns.

Collection Types

Naming Conventions

• Collection names: snake_case, plural (contacts, order_items, task_comments)
• Field names: camelCase (firstName, orderDate, totalAmount)
• Relation fields: describe the relationship (company, assignee, tags)
• Through tables: combine both collection names (order_products, user_roles)

System Fields

Every collection should include:

NocoBase adds these automatically when enabled in collection settings.

Design Process

Step 1: Identify Entities

List all data entities the application needs. Think in terms of:

• Core entities: Main business objects (Contacts, Orders, Products)
• Supporting entities: Reference data (Categories, Statuses, Tags)
• Junction entities: Many-to-many bridges (OrderItems, UserRoles)

Step 2: Define Fields per Entity

For each entity, list fields with types:

contacts:
  - name: string (required)
  - email: email (unique)
  - phone: phone
  - status: singleSelect (Lead, Active, Inactive)
  - avatar: attachment
  - notes: richText
  - birthday: date

Step 3: Map Relations

Draw entity relationships:

companies ──< contacts (one company has many contacts)
contacts ──< deals (one contact has many deals)
deals >──< products (many-to-many via deal_products)

Step 4: Create in Order

1. Independent collections (no foreign keys): companies, products, categories
2. Dependent collections: contacts (needs companies), deals (needs contacts)
3. Junction collections: deal_products (needs deals + products)
4. Set up relations between collections
5. Add computed/formula fields

Collection Architecture Patterns

Master-Detail

orders (master)
  ├── order_items (detail, hasMany)
  └── order_notes (detail, hasMany)

Self-Referencing (Tree)

categories
  └── parent (belongsTo → categories, self-reference)
  └── children (hasMany → categories)

Polymorphic

comments
  - commentable_type: string (posts, products, orders)
  - commentable_id: bigInt
  → Can belong to different collection types

Soft Delete

Add field: deletedAt (datetime, nullable)
Filter by default: where deletedAt IS NULL

Inheritance

NocoBase supports collection inheritance:

base_collection: people
  - name, email, phone

child_collection: employees (inherits people)
  - department, salary, hireDate

child_collection: customers (inherits people)
  - company, tier, lastPurchase

Inherited collections share base fields and can add their own.

Tools for Collection Inspection

Workflow: Inspect Existing Schema Before Designing

Before creating new collections, always check what already exists:

Step 1: collection_list → get all collections
Step 2: collection_get → for each relevant collection, get field details
Step 3: Identify gaps — what collections/fields are missing
Step 4: Design new collections considering existing relations

Example:

collection_list()
  → [{ name: "users" }, { name: "companies" }, { name: "products" }]

collection_get("companies")
  → { name: "companies", fields: [
       { name: "name", type: "string" },
       { name: "industry", type: "singleSelect" },
       { name: "contacts", type: "hasMany", target: "contacts" }
     ] }

// Now design "contacts" knowing that "companies" already has a hasMany relation

Workflow: Validate Schema Design

After designing on paper, verify against the instance:

Step 1: collection_list → confirm no naming conflicts
Step 2: collection_get → check existing collections for relation compatibility
Step 3: Document creation order based on dependencies

Best Practices

1. Plan before building — sketch ERD on paper or whiteboard
2. Inspect existing schema — always run collection_list and collection_get before adding new collections
3. Normalize data — avoid storing the same data in multiple places
4. Use proper field types — email for emails, phone for phones (enables validation)
5. Enable system fields — always include createdAt, updatedAt, createdBy
6. Name consistently — stick to naming conventions project-wide
7. Start with core entities — build the minimum viable data model first
8. Use relations, not IDs — configure proper belongsTo/hasMany instead of raw foreign keys
9. Design for UI — consider what blocks and views you'll need when choosing field types