Data Model and Schema Design
Core model
Every record type is a resource backed by a schema. Built-in namespaces (nms, xtk) cover recipients, deliveries and logs; custom resources live in your own namespace. You extend a built-in schema to add fields or links, but you cannot remove or retype an out-of-the-box field. Understand primary keys (usually an auto-increment id), external IDs used for reconciliation, enumerations, and cardinality: 1-1, 1-N and N-N. An N-N relationship needs a link table; a 1-N link stores the key on the many side, while a collection link is a navigation shortcut that may require a reverse link.
Traps
Questions often confuse the schema name (technical, immutable) with its label (UI, translatable). Another trap is direction: a collection link on Recipient to Orders does not by itself store data; the foreign key lives on Order. Deleting a field destroys its data and breaks references. Changing a link cardinality after data exists is not a free edit. Filtering dimensions and target mappings must match the schema you query.
Rule of thumb
Model the many side as the owner of the foreign key, and only add collection links where users need to navigate or target. For imports, always define a stable external ID (for example crmId) rather than relying on email.
Worked example: Orders belong to one recipient. Create custom resource Order with orderId (external ID, unique), amount, orderDate, and a 1-N link recipient to nms:recipient. On Recipient, add collection link orders with the reverse link set to recipient. Target Orders when you need order-level filters; target Recipients when you need one message per person and aggregated order data.