RelationshipDefinition

Concept: Relationships and Lookups →

A declared relationship between two objects, or between an object and a closed value set: the JSON5-deserializable author-facing form of a *_relationship.json5 file. Accepts either bare-string or nested endpoint-map forms for from and to (cascade-delete and state-machine transitions are set through the nested map forms, not as separate top-level keys).

Properties

Property	Type	Required/Default	Constraints	Meaning
relationshipKey	string	Required	min length 1; max length 63; pattern ^[a-z][a-zA-Z0-9]*$	Unique key for this relationship within its module.
label	string	Required		Human-readable label shown in the UI.
cardinality	enum (Cardinality)	Optional		Cardinality for object and polymorphic targets.
pick	enum (Pick)	Optional		Selection cardinality for value-set targets.
required	boolean	Optional (default: false)		Whether a target record is mandatory, for object and polymorphic targets.
uniquePair	boolean	Optional (default: false)		Whether each (from, to) pair may appear at most once, for manyToMany relationships.
pairing	enum (Pairing)	Optional		Directionality for a self-referential many-to-many relationship.
fromField	string	Optional	min length 1; max length 63; pattern ^[a-z][a-zA-Z0-9]*$	Name of the field synthesized on the from side.
toField	string	Optional	min length 1; max length 63; pattern ^[a-z][a-zA-Z0-9]*$	Name of the inverse field synthesized on the to side.
strategy	enum (Strategy)	Optional		Overrides the storage strategy the compiler would otherwise infer from to and cardinality/pick.
objectKey	string	Optional	min length 1; max length 63; pattern ^[A-Z][a-zA-Z0-9]*$	Explicit object key for the junction object synthesized by this relationship, for manyToMany relationships.
ordered	boolean	Optional (default: false)		When true, adds a sortOrder integer property to junction edges.
temporal	boolean	Optional (default: false)		When true, declares that this relationship participates in bitemporal modeling.
mutable	boolean	Optional (default: true)		Controls whether the reference can change after the record is created.
fromLabel	string	Optional		Overrides the label of the field synthesized on the from side.
toLabel	string	Optional		Overrides the label of the inverse field synthesized on the to side.
filter	string	Optional		A formula expression that narrows the valid target records for this relationship.
sharing	SharingPolicy object	Optional (default: {"edge":"owner"})		Opt-in read-visibility policy for junction edge rows.

relationshipKey

Unique key for this relationship within its module. See RelationshipDefinition::relationship_key.

label

Human-readable label shown in the UI. See RelationshipDefinition::label.

cardinality

Cardinality for object and polymorphic targets. See RelationshipDefinition::cardinality.

pick

Selection cardinality for value-set targets. See RelationshipDefinition::pick.

required

Whether a target record is mandatory, for object and polymorphic targets. See RelationshipDefinition::required.

uniquePair

Whether each (from, to) pair may appear at most once, for manyToMany relationships. See RelationshipDefinition::unique_pair.

pairing

Directionality for a self-referential many-to-many relationship. See RelationshipDefinition::pairing.

fromField

Name of the field synthesized on the from side. See RelationshipDefinition::from_field.

toField

Name of the inverse field synthesized on the to side. See RelationshipDefinition::to_field.

strategy

Overrides the storage strategy the compiler would otherwise infer from to and cardinality/pick. See RelationshipDefinition::strategy.

objectKey

Explicit object key for the junction object synthesized by this relationship, for manyToMany relationships. See RelationshipDefinition::object_key.

ordered

When true, adds a sortOrder integer property to junction edges. See RelationshipDefinition::ordered.

temporal

When true, declares that this relationship participates in bitemporal modeling. See RelationshipDefinition::temporal.

mutable

Controls whether the reference can change after the record is created. See RelationshipDefinition::mutable.

fromLabel

Overrides the label of the field synthesized on the from side. See RelationshipDefinition::from_label.

toLabel

Overrides the label of the inverse field synthesized on the to side. See RelationshipDefinition::to_label.

filter

A formula expression that narrows the valid target records for this relationship. See RelationshipDefinition::filter.

sharing

Opt-in read-visibility policy for junction edge rows. See RelationshipDefinition::sharing.

Accepted Forms

from

• Bare string — the source object’s qualified name, e.g. "core.Account".
• Object map — { object, onTargetDelete }:

Property	Type	Required/Default	Constraints	Meaning
object	string	Required		Qualified name of the source object, e.g. "core.Account".
onTargetDelete	enum (OnParentDelete)	Optional		Action to take on junction edges referencing this side when the source record is deleted.

onTargetDelete

Action to take on junction edges referencing this side when the source record is deleted. Only valid on a manyToMany relationship — see InferenceError::OnTargetDeleteFromRequiresJunction.

to

• Bare string — a single target object, e.g. "core.Account".
• Array of strings — a polymorphic target (two or more objects), e.g. ["core.Account", "core.Contact"].
• Values map — { values: [...] } — a closed value-set target.
• Object map — { object, onTargetDelete }:

Property	Type	Required/Default	Constraints	Meaning
object	string	Required		Qualified name of the target object, e.g. "core.Account".
onTargetDelete	enum (OnParentDelete)	Optional		Action to take on this record when the referenced (target) record is deleted.

onTargetDelete

Action to take on this record when the referenced (target) record is deleted. Absent means the compiler derives a default from required — see OnParentDelete.

• Poly map — { objects, onTargetDelete }:

Property	Type	Required/Default	Constraints	Meaning
objects	array of string	Required	must not be empty; elements must not repeat	Qualified names of the target objects, e.g. ["core.Account", "core.Contact"].
onTargetDelete	enum (OnParentDelete)	Optional		Action to take on referencing records when any target record in objects is deleted.

onTargetDelete

Action to take on referencing records when any target record in objects is deleted. Absent means the compiler derives a default from required — see OnParentDelete.

• Value-set transitions map — { values, transitions }:

Property	Type	Required/Default	Constraints	Meaning
values	array of string	Required		The closed set of valid string values, e.g. ["open", "closed"].
transitions	array of EnumTransition object	Optional		Allowed state transitions between values.

transitions

Allowed state transitions between values. Absent means any value is reachable from any other. See EnumTransition.

Cardinality

How many records participate on each side of the relationship.

Required when to names a single object or multiple objects. Not valid together with pick, which serves the same role for value-set targets.

Value	Status	Description
oneToOne		Exactly one record on each side of the relationship.
manyToOne		Many records on the from side may reference the same record on the to side.
manyToMany		Many records on both sides may reference each other.

EdgeVisibility

Read-visibility policy for junction edge rows.

owner (the default) restricts read access to the principal who created the edge. endpoints widens read access: a principal may read an edge when it can read both endpoint records (the from-side and the to-side), in addition to the creator. Write access (create, update, delete) is always restricted to the creator, regardless of this policy.

Value	Status	Description
owner		Only the edge’s creator may read it.
endpoints		A principal may read the edge when it can read both endpoint records, in addition to the creator.

EnumTransition

A state machine transition rule for an enum field.

Declares that a field value is allowed to change from from to any value in to. An empty to vec means the state is terminal (no transitions out).

Property	Type	Required/Default	Constraints	Meaning
from	string	Required		The source state this rule applies to.
to	array of string	Required		Allowed destination states.

to

Allowed destination states. Empty means terminal.

OnParentDelete

Controls what happens to child records when the referenced (parent) record is deleted.

Authored as one of three values in *_relationship.json5 metadata: "restrict", "setNull", "cascade". When not specified, the default is derived from the field’s required property: setNull when the reference is optional, restrict when it is required (a required reference cannot be cleared to null on parent delete). Declaring required: true together with onParentDelete: "setNull" is an invalid combination — the platform auto-corrects it to restrict and reports a warning diagnostic.

Value	Status	Description
restrict		Prevents deletion of the parent record while any child record still references it — the delete fails with a database error.
setNull		Clears the reference on all child records when the parent record is deleted; the children remain, with an empty reference.
cascade		Deletes all child records when the parent record is deleted.

Pairing

Directionality of a self-referential many-to-many relationship — one where from and to name the same object.

Valid only when cardinality: manyToMany and from and to name the same object.

Value	Status	Description
directed		fromField and toField have distinct meaning — the two are not interchangeable.
symmetric		The relationship is symmetric — the order of fromField and toField carries no meaning.

Pick

How many values from the value set a record may select.

Required when to is a value set. Not valid together with cardinality, which serves the same role for object and polymorphic targets.

Value	Status	Description
one		A record selects exactly one value from the set.
many		A record may select any number of values from the set.

SharingPolicy

Opt-in visibility policy for a relationship.

Only meaningful for manyToMany relationships — see edge.

Property	Type	Required/Default	Constraints	Meaning
edge	enum (EdgeVisibility)	Optional (default: "owner")		Read-visibility rule for junction edge rows.

edge

Read-visibility rule for junction edge rows. Defaults to owner.

Strategy

Physical storage strategy for a relationship — how it compiles to database structure.

The compiler infers this automatically from to and cardinality/pick; setting strategy explicitly overrides the inference. An explicit value must still satisfy the same coherence rules as the inferred value.

Value	Status	Description
enum		A value-set target with pick: one.
arrayEnum		A value-set target with pick: many.
lookup		A single-object target with cardinality: oneToOne or manyToOne.
junction		A single-object target with cardinality: manyToMany.
polymorphicLookup		A polymorphic (multi-object) target with cardinality: oneToOne or manyToOne.
polymorphicJunction		A polymorphic (multi-object) target with cardinality: manyToMany.

Example

{
  "from": "example",
  "label": "example",
  "relationshipKey": "example",
  "to": "example"
}