Reference Properties

Reference Properties let you add structured metadata directly to references (relationships) between objects. While a standard attribute on a type describes the objects themselves, a Reference Property describes the link between two objects — similar to properties on edges in a graph database.

Key terms:

• Reference — an attribute of type REFERENCE on a type, pointing to one or more objects of another type (or the same type, for self-references).
• Reference Property — a property defined on a Reference attribute, with its own type (Text, Date, Integer, Option, Priority, etc.) describing what can be stored for each relationship.
• Reference Value — the actual set of objects referenced by a given object through that attribute.
• Reference Property Value — the values assigned to the Reference Properties for one specific reference within a Reference Value.

Why use Reference Properties

Adding properties to relationships, not just objects, unlocks more expressive data models:

Scenario	Relationship	Example properties
Social networks	Friendship between two users	Since (Date), Interaction Frequency (Integer)
Recommendations	User purchased Product	Purchase Date, Quantity, Rating
Supply chain	Supplier → Manufacturer transaction	Transaction Date, Volume, Cost
Fraud detection	Account transferred funds to Account	Amount, Timestamp, Transaction Type
Research	Researcher authored Publication	Role, Contribution %, Publication Date
Telecom	User called Device/User	Call Duration, Call Type, Timestamp

Configuring a Reference Property

1. Go to your space's schema and find the type that has (or will have) a Reference attribute.
2. On the Reference attribute's row, open the ⋮ menu and choose Properties. The menu item appears only for REFERENCE attributes.
3. Add one or more properties: give each a name (e.g. Since, Rating), choose its type, optionally write a description, and select Add.

A property's name and description can be edited later. Its type is chosen when it is created and cannot be changed. An Integer, Decimal, Option or Priority property has a settings icon (Configure) beside its delete icon, which opens its configuration, as for an attribute.

Property types

Type	Stores	Configuration
Text	A line of text	—
Integer	A whole number	Formatting
Decimal	A number with decimals	Formatting
Boolean	Yes or no	—
Date	A date	—
DateTime	A date and time	—
Option	One of a list of options you define	Options, and whether several may be picked
Priority	One priority, such as High or Low	Priorities and their colors

Formatting numbers

An Integer or Decimal property can show its values as a currency, a unit or a percentage, in the same way as an Integer or Decimal attribute. Select the property's settings icon, choose the formatting type, then its currency or unit. A preview such as €1,234 shows how values will read. Select Save to apply it.

Formatting only changes how values are displayed. Values are stored and searched as plain numbers.

Options

An Option property lets each reference hold one of a list of options, such as a Role of Primary or Secondary on a supplier relationship. Select the property's settings icon to add, rename or reorder its options, and to choose Allow several options per reference, then select Save. A new Option property has no options and allows one option per reference.

• A value must name one of the property's options. Unlike an Option attribute, a reference property does not add a new option when a value names one that doesn't exist.
• An option that a value uses cannot be removed, and a property cannot go back to one option per reference while a reference holds several. Change those values first.
• Renaming an option keeps the values that use it, and search finds them by the new name.

Priorities

A Priority property lets each reference hold one priority, such as the Importance of a supplier to a product. A new Priority property starts with the same priorities as a Priority attribute: Highest, High, Medium, Low and Lowest. Select the property's settings icon to add, rename, recolor or reorder them, highest first, then select Save.

• A reference holds at most one priority, and a value must name one of the property's priorities.
• A priority that a value uses cannot be removed. Change those values first.
• Renaming a priority keeps the values that use it, and search finds them by the new name.

Working with values

• Users with the right permissions can add or edit property values when hovering over a referenced object, or from the object details view.
• Each individual reference (each linked object) has its own independent set of property values.
• Property values are shown with the referenced object in the object details view and when hovering over a reference.
• Objects can be filtered on their references' property values in StarQL, for example Supplier -> starQL(;Role = Primary). See filtering on Reference Properties for the syntax.
• A Rollup attribute totals one property across all of an object's references and stores the answer on the object, which makes that total available as a column, a sort, a StarQL filter and a widget value.

Limitations

• Only available on attributes of type Reference.
• Supported property types today: Text, Integer, Decimal, Boolean, Date, DateTime, Option and Priority.
• Property values themselves can't be shown as columns in table, board or gallery views, used to sort objects, aggregated in widgets, used in automations, or included in imports and exports. A Rollup attribute lifts the first four for a single numeric property by totalling it onto the object, where it behaves like any other number. Imports and exports stay out of reach: a Rollup is worked out by Starhive, so nothing can be imported into one.
• Bulk editing of reference property values isn't supported in the UI — use the API instead.

See also: Attribute, Reference Attribute Type.