Type Creation Guide

Showing 3 of 6

1. 1 Select type category from foundation types

   Every domain type MUST extend a foundation type. Decision tree:
   
     Does the entity have unique identity (UUID), CRUD lifecycle, metadata?
       YES → type_category: document (Property, Person, Booking, Agent)
       NO  → Does it enumerate fixed values?
         YES → type_category: dictionary (property-type, booking-status)
         NO  → Is it a grouped collection?
           YES → type_category: catalogue
           NO  → Is it a monetary value?
             YES → type_category: money
             NO  → Is it a media asset?
               YES → type_category: image
               NO  → Likely type_category: document (default for domain entities)
   
   Check existing foundation types:
     sbx type list --level foundation --for-agent

2. 2 Determine reference semantics (Decision #0105)

   How other entities reference instances of this type:
   
     identity   — Referenced by UUID FK. Independent lifecycle.
                  Use for: Property, Person, Booking, Agent
                  PK pattern: {type}_id UUID
   
     embedded   — Value copied into parent. No independent lifecycle.
                  Use for: Money, Address, GeoPoint
                  Storage: JSONB column or flattened columns
   
     code       — Referenced by code string. Singleton per code.
                  Use for: Dictionary entries (property-type, status)
                  FK pattern: {type}_code VARCHAR
   
   Check existing type semantics:
     sbx type get <name> --for-agent  # shows reference_semantics section

3. 3 Identify attribute-groups (cascade-delete dependencies)

   Attribute-groups are structured sub-data with NO independent lifecycle.
   They cascade-delete with the parent entity.
   
   Pattern: If a set of fields always belongs to ONE parent and has no
   meaning alone → attribute-group (not a separate entity).
   
   Examples from Property type:
     PropertyLocation  — city, province, region, coordinates
     PropertyRooms     — bedrooms, bathrooms
     PropertySizes     — land_sqm, house_sqm, living_sqm
     PropertyFeatures  — pool, garden, parking, security (booleans)
   
   Storage: dependent table with PK=FK to parent, or JSONB column.
   Go: pointer to struct (*PropertyLocation) — nil means not set.