---
title: Relationships between objects
description: Define and configure relationships between PingIDM managed objects, including bidirectional relationships and _refProperties metadata
component: pingidm
version: 7.5
page_id: pingidm:objects-guide:relationships
canonical_url: https://docs.pingidentity.com/pingidm/8.1/objects-guide/relationships.html
llms_txt: https://docs.pingidentity.com/pingidm/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
keywords: ["Data Object Model", "Relationships", "Roles", "Organizations"]
superseded_by: https://docs.pingidentity.com/pingidm/8.1/objects-guide/relationships.html
section_ids:
  define-relationship-type: Define a relationship type
---

# Relationships between objects

Relationships are references between managed objects. [Roles](roles.html) and [Organizations](organizations.html) are implemented using relationships, but you can create relationships between any managed object type.

## Define a relationship type

Relationships are defined in your managed object configuration *(tooltip: You can edit the managed object configuration over REST at the config/managed endpoint, or directly in the conf/managed.json file.)*. The default configuration includes a relationship named `manager` that lets you configure a management relationship between two managed users. The `manager` relationship is a good example from which to understand how relationships work.

The default `manager` relationship is configured as follows:

```json
"manager" : {
    "type" : "relationship",
    "validate" : true,
    "reverseRelationship" : true,
    "reversePropertyName" : "reports",
    "description" : "Manager",
    "title" : "Manager",
    "viewable" : true,
    "searchable" : false,
    "usageDescription" : "",
    "isPersonal" : false,
    "properties" : {
        "_ref" : {
            "description" : "References a relationship from a managed object",
            "type" : "string"
        },
        "_refProperties" : {
            "description" : "Supports metadata within the relationship",
            "type" : "object",
            "title" : "Manager _refProperties",
            "properties" : {
                "_id" : {
                    "description" : "_refProperties object ID",
                    "type" : "string"
                }
            }
        }
    },
    "resourceCollection" : [
        {
            "path" : "managed/user",
            "label" : "User",
            "query" : {
                "queryFilter" : "true",
                "fields" : [
                    "userName",
                    "givenName",
                    "sn"
                ]
            }
        }
    ],
    "userEditable" : false
},
```

Most of these properties apply to any [managed object type](creating-modifying-managed-objects.html). Relationships have the following specific configurable properties:

* `type` (string)

  The object type. Must be `relationship` for a relationship object.

* `returnByDefault` (boolean `true, false`)

  Specifies whether the relationship should be returned as part of the response. The `returnByDefault` property is not specific to relationships. This flag applies to all managed object types. However, relationship properties are not returned by default, unless explicitly requested.

* `reverseRelationship` (boolean `true, false`)

  Specifies whether this is a [bidirectional relationship](reverse-relationships.html).

* `reversePropertyName` (string)

  The corresponding property name, in the case of a [bidirectional relationship](reverse-relationships.html). For example, the `manager` property has a `reversePropertyName` of `reports`.

* `_ref` (JSON object)

  Specifies how the relationship between two managed objects is referenced.

  In the relationship definition, the value of this property is `{ "type" : "string" }`. In a managed user entry, the value of the `_ref` property is the reference to the other resource. The `_ref` property is described in more detail in [Create a relationship between two objects](relationships-between-objects.html).

* `_refProperties` (JSON object)

  Any required properties from the relationship that should be included in the managed object. The `_refProperties` field includes a unique ID (`_id`) and the revision (`_rev`) of the object. `_refProperties` can also contain arbitrary fields to support metadata within the relationship.

* `resourceCollection` (JSON object)

  The collection of resources (objects) on which this relationship is based (for example, `managed/user` objects).