Relationships and containment

Moltaro connects records through a small set of named mechanisms. Knowing which one is in play tells you where it is configured and how it behaves:

• a Reference field links a record to exactly one record of another entity definition;
• an Inverse reference field shows the reverse of one Reference as a list;
• an Association is a separate entity definition that models a many-to-many relationship as its own governed records;
• containment describes a parent-child business relationship. Access is still decided by the child’s current Security Statements and Permission Assignments, which may explicitly traverse an allowed parent or catalogue fact.

One terminology warning: record-to-record links are schema References or Associations. Human ownership such as Owner, Assignee, or Reviewer is modeled as a governed Responsibility and authorized through Assignment Rules. See Entity security.

Reference fields

A Reference is a schema field (Constructor > Entity Explorer > entity > Schema) that stores a link to one record of a configured target entity definition. A Reference is strictly single-value; there is no multi-reference field type. The target entity is chosen at creation and cannot change later.

Reference settings with operational consequences:

• Delete behavior — “Prevent deletion while referenced” (the safe default), “Delete linked records”, or “No action”. Preventing deletion returns a clear error until every active or archived record stops pointing at the target. Cascade permanently deletes the pointing records together with the target and is available only for References in the primary table. No action can leave a link that later resolves as NotFound.
• Archive behavior — cascade archives and restores the records that reference the current record together with it.
• Audit roll-up — “Show in referenced record history”: this record’s audit events also appear in the referenced record’s history.
• Allow sorting — lets lists sort by the linked record’s display value. The Constructor warns that sorting this way can ignore record-level security on the target entity.

In runtime forms a Reference renders as a list, long list, or lookup picker, and can display as a simple label or as breadcrumbs following a configured reference path.

In API JSON, a Reference is written as the target record’s id and read back as a compact resolved preview only when the source field is readable and the target record grants root View. Missing and inaccessible targets have one non-disclosing unavailable shape; neither the target identity nor presentation details are returned.

Delete behavior affects only permanent deletion. Archiving a record uses the separate Archive behavior. A record may delete itself even if it points to itself, and its own child rows do not block deletion of that same aggregate. Existing References configured as No action keep that setting; creating a new Reference defaults to Prevent deletion while referenced.

Inverse reference fields

An Inverse reference is declared explicitly on the entity being pointed at. It pairs with one primary-table Reference field on the source entity and materializes the list of records whose paired Reference points at the current record. It has no stored column and cannot be required.

Inverse references power much of the related-record experience:

• related-data lists and tables on detail pages and drawers;
• aggregate calculated fields such as SUM, COUNT, AVG, MIN, and MAX over the linked child records;
• reverse lookups in queries (for example, records with or without any pointing records).

An inverse reference can also be written: a create or update payload may set it to a list of source record ids, and the runtime rewrites the paired Reference on each affected source record in the same transaction. This requires update access on every affected source record.

Associations: many-to-many relationships

When many records must link to many records, Moltaro models the relationship as an Association — an entity definition whose type is Association (entity definitions have a type: Data, Association, Part, or the Dictionary creation preset).

Creating an association uses a wizard with Base, Left endpoint, Right endpoint, and Security steps. It generates:

• two required endpoint Reference fields on the association entity, one for each side;
• a generated Inverse reference field on each endpoint entity, so both sides list their association rows;
• a binding that locks these generated fields together.

An association row is itself a governed record: it has its own list page, drawer, permissions, and an always-on audit trail, and it can carry its own fields (for example, a role, share, or valid-from date on the link). Both endpoint records’ histories include the association’s audit events.

Rules worth knowing: endpoints can target only Data entity definitions, endpoint values are required and immutable after creation, no entity may declare a Reference to an association, and associations cannot contain Table fields. Ordinary one-to-many relationships should stay Reference + Inverse reference; associations are specifically for many-to-many.

Child rows are not relationships

A Table field holds repeatable child rows inside one record. Rows have no independent identity, access, or detail page, so they are structure inside a record, not a relationship between records. A Table column can itself be a Reference to another entity.

Structure is not implicit access

References, association endpoints, parent-tree fields, Parts, and catalogs describe business structure. They do not copy or inherit Entity access. An active Security Statement can traverse an explicitly supported reference or catalogue fact, while root View and field projection still apply separately to every Entity record. See Security Statements.

Relationships in the API

• Reference and Inverse reference values are read and written through the Entity Instances operations — see query records and the instance read operation.
• Association rows are ordinary entity instances of the association definition and use the same instance endpoints.
• Responsibilities have dedicated Add, Replace, Close, candidate, and history operations under the Entity runtime surface.

Where to go next

• Read Relationships between records for the user-facing view.
• Read Fields and schema for Reference and Inverse reference as field types.
• Read Catalogs for hierarchy and catalog security.