About Object Reference Notation

Object reference notation lets you identify a related object record by a unique field value instead of its record ID. Use it when setting an object reference field on a document or object record.

For example, instead of looking up the ID of a Product record and passing 00P000000000202, you can write document_product__vr.name__v with the value Cholecap. Vault resolves the related record when the operation runs.

Why Use Object Reference Notation?

Setting object reference fields using record IDs requires an extra query step to look up the ID before making the API or SDK call. The extra query step adds overhead and complicates integration code.

Object reference notation is useful in Vault to Vault Connections, where the same object record has different IDs in each Vault. Integrations that rely on IDs must map or resolve those IDs per Vault.

Notation Styles

Vault supports two object reference notation styles: field name notation and relationship name notation. Both use dot notation to combine an identifier for the object reference field with a unique field on the related object.

The unique field on the related object must have unique: true in the object's field metadata. For example, commonly used unique fields are name__v and external_id__v.

Field Name Notation

Field name notation uses the API name of the object reference field:

product__v.name__v

Relationship Name Notation

Relationship name notation uses the relationship name of the object reference field. For document fields, the relationship name follows the pattern document_{field_name}__vr:

document_product__vr.name__v

Considerations

Keep the following in mind when working with object reference notation:

Write-only: Object reference notation is for setting values only. When you retrieve field values, Vault returns the record ID, not the notation used to set it. For example, retrieving values with Vault API or Vault Java SDK returns the record ID.
Multi-value document fields: For document object reference fields that support multiple values, pass the values as a list or as a single comma-separated string. For example: documentVersion.setValue("document_multiref__cr.name__v", VaultCollections.asList("Record1-Text,Record2-Text,Record3-Text"));
Uniqueness: If the notation resolves to more than one record, the operation fails. Use a field that is guaranteed to be unique in your Vault, or use external_id__v for cross-environment portability.