Define Meaningful Record Relationships

Purpose

Administrators need a shared vocabulary for connections the organization tracks. Relationship types make those connections recognizable from either endpoint.

How It Works

The administrator chooses the two record types and labels for both directions. The definition includes cardinality, dating, primary designation and deletion policy. Platform validates the endpoints and rejects unsupported cascades. A saved type lets staff create links under that vocabulary. Labels and mutable policies can be maintained while the type shape remains fixed. Retiring a used type preserves its existing links. Owner relationships cannot be retired while custom-object definitions depend on them.

Relationships

Record types provide endpoints. Custom objects may select a relationship as owner, and link maintenance uses the type definition.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes: Administrators need a shared vocabulary for connections the organization tracks.Retiring a used type preserves its existing links.
Surfaces: consoleapi
Postconditions: Type mutations leave security events identifying the changed fields.
Intent sources: services-platform:docs/milestones/plans/PLAT-M6-plan.md#4. Assumptions A1, A2; 5. D1, D3, D5 (approved 2026-10-21)services-platform:docs/proposals/custom-objects/09-decisions.md#D-04, D-12, D-16

Controls

23 controls apply, from the corpus control catalogue.

TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-DAT-001 TC-DAT-003 TC-DAT-004 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-003 TC-PI-005 TC-PRV-001 TC-PRV-002 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-TEN-004 TC-VEN-001 TC-VEN-002 TC-VEN-003

Permissions

Key	Checked at	Scope
`platform.association-types.read`	api	tenant
`platform.association-types.create`	api	tenant
`platform.association-types.update`	api	tenant
`platform.association-types.delete`	api	tenant

Business Rules

10 rules, 10 to be proved before approval. A rule's product intent is derived from its origin: 10 confirmed by a product decision, the rest inheriting this capability's confirmed.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Confirmed	A relationship type has a permanent bounded key, labels from both sides, one-to-one, one-to-many or many-to-many cardinality, dating and primary settings and detach, cascade or restrict rules for each side, rejecting invalid choices. origin: services-platform:docs/milestones/plans/PLAT-M6-plan.md#4. Assumptions A1 proved by `ATS-PFM-MTD-017-01`, `TST-PFM-MTD-036`, `TST-PFM-MTD-041`	validation	api, service, database	test services-platform:modules/associations/tests/e2e/associations.e2e.spec.js#answers 400 to an unknown cardinality, naming the three
`02`must prove Confirmed	Endpoints may be contacts, organizations or active custom objects of the workspace, including two sides of the same type, but not draft custom objects. origin: services-platform:docs/milestones/plans/PLAT-M6-plan.md#5. D1 (Andrew, 2026-10-21: contacts, organizations, custom records) proved by `ATS-PFM-MTD-017-02`, `TST-PFM-MTD-036`, `TST-PFM-MTD-041`, `TST-PFM-MTD-045`	validation	service	test services-platform:modules/associations/tests/e2e/associations.e2e.spec.js#answers 400 to a type of a draft custom object, naming it as not active
`03`must prove Confirmed	A relationship type cannot define a cascade that would delete a contact or organization. origin: services-platform:docs/milestones/plans/PLAT-M6-plan.md#4. Assumptions A2 proved by `ATS-PFM-MTD-017-03`, `TST-PFM-MTD-016`, `TST-PFM-MTD-041`	validation	service	test services-platform:modules/associations/tests/integration/services/persistence/association-types.integration.spec.js#refuses a cascade that would delete a native record, writing nothing
`04`must prove Confirmed	Endpoint types, cardinality and dating are immutable; versioned changes may alter labels and policies, and primary support cannot be disabled while an in-force primary remains. origin: services-platform:docs/milestones/plans/PLAT-M6-plan.md#4. Assumptions A1 proved by `ATS-PFM-MTD-017-04`, `TST-PFM-MTD-041`	invariant	service	test services-platform:modules/associations/tests/integration/services/persistence/association-types.integration.spec.js#refuses a change of cardinality, the shape of a type being immutable, and leaves the row as it was
`05`must prove Confirmed	Removal deletes an unused type or deactivates a used type, preserving links and blocking new ones while allowing subsequent revival. proved by `ATS-PFM-MTD-017-05`, `TST-PFM-MTD-041`	lifecycle	service	test services-platform:modules/associations/tests/integration/services/persistence/association-types.integration.spec.js#deactivates a type an association names instead of deleting it
`06`must prove Confirmed	A relationship named as an object owner cannot be deleted or deactivated regardless of object status, and the refusal names the affected objects and required owner change. origin: services-platform:docs/milestones/plans/PLAT-M6-plan.md#5. D3 (Andrew, 2026-10-21: "Refuse, name the object") proved by `ATS-PFM-MTD-009-13`, `ATS-PFM-MTD-017-06`, `ATS-PFM-MTD-017-09`, `TST-PFM-MTD-023`, `TST-PFM-MTD-041`	validation	service	test services-platform:modules/associations/tests/integration/services/persistence/association-types.integration.spec.js#refuses deactivating the type of one object, naming it by its label and what to change first
`07`must prove Confirmed	Required-link flags can be stored on a type but have no enforcement in record or link writes. no proof recorded yet	validation	service	unknown FND-PFM-MTD-013
`08`must prove Confirmed	The approved relationship limits are one hundred types per workspace and twenty touching an object, but current code enforces neither limit. origin: services-platform:docs/proposals/custom-objects/09-decisions.md#D-16 (approved 2026-10-18) no proof recorded yet	validation		documented services-platform:docs/proposals/custom-objects/09-decisions.md#D-16
`09`must prove Confirmed	Type mutations audit changed field names and advance the workspace query description so relationship changes become available to queries. proved by `ATS-PFM-MTD-017-07`, `TST-PFM-MTD-041`	policy	service, database	test services-platform:modules/associations/tests/integration/services/persistence/association-types.integration.spec.js#records a delete and a deactivation in the security trail, each by its action
`10`must prove Confirmed	The relationship-type editor explains choices and validation issues, saves no invalid definition and remains unavailable to standard users. origin: services-platform:docs/milestones/plans/PLAT-M6-plan.md#PLAT-M6-S02, S12 proved by `ATS-PFM-MTD-017-03`, `ATS-PFM-MTD-017-08`, `TST-PFM-MTD-016`, `TST-PFM-MTD-026`, `TST-PFM-MTD-041`	policy	console	test react-console:acceptance/custom-objects/playwright/journeys/PLAT-M6-S02.spec.ts#PLAT-M6-S02: a relationship type with a missing label, a cascade onto contacts or a duplicate id is refused and nothing is saved

Scenarios

Id	Given	When	Then	Provenance
`01`	An administrator opens relationship configuration.	Define dated many-to-many Crew between contacts and boats.	The contact and boat pages offer the relationship card using the appropriate directional label.	test react-console:acceptance/custom-objects/playwright/journeys/PLAT-M6-S01.spec.ts#PLAT-M6-S01: an administrator defines Crew and both Osprey's and Tom's pages show it under their own label

Edge Cases

Id	Given	When	Then	Provenance
`02`	Boat selects a contact ownership type.	Attempt to retire that type.	The refusal identifies Boat as a dependent owner definition.	test react-console:acceptance/custom-objects/playwright/journeys/PLAT-M6-S09.spec.ts#PLAT-M6-S09: a relationship type is relabelled, retired, revived and removed, and Boat's owner type cannot be retired

Planning

Implementation

Define Meaningful Record Relationships ​

Purpose ​

How It Works ​

Relationships ​