Recently, I worked on the specification for a RESTful API designed to capture information about individuals, organisations and the relationships between them.

Modelling relationships between parties (i.e., individuals and organisations) can be complex, however, it's important to understand and record them correctly.

Roles and Relationships

Symmetrical Relationships

A relationship is symmetrical if the roles on each end are identical (they can be substituted for each other without changing the semantics of the relationship). Let's look at an example:

Party Role Relationship Role Party
Lisa Simpson Sister Sibling Sister Maggie Simpson

When a relationship is symmetrical, role-related information can be associated with the relationship.

Asymmetrical Relationships

A relationship is asymmetrical if each Party plays a different role in the relationship. Let's look at some examples:

Party Role Relationship Role Party
Homer Simpson Husband Marriage Wife Marge Simpson
Homer Simpson Employee Employment Employer Springfield Nuclear Power Plant
Homer Simpson Member Membership Organisation The Stonecutters

Most relationships are asymmetrical as one Party has capabilities (e.g., knowledge, skills and experience) that complement those of the other Party.

When a relationship is asymmetrical, role-related information must be associated with a role.

The English Language

Sometimes you will find that the English language does not always distinguish clearly between relationships and roles, for example:

Party Role Relationship Role Party
Homer Simpson Partner Partnership Partnership The Be Sharps

This is partly because some relationships are symmetrical (as described above), so the role and the relationship become somewhat confused, and partly because in normal English usage the difference between the two often just isn’t relevant.

Sometimes it can be difficult to determine the appropriate name to use for a reciprocal role, for example:

Party Role Relationship Role Party
Homer Simpson Trustee Trusteeship Trust The Simpson Family Trust
Homer Simpson Member Membership Association Mensa International

This is often because roles are more commonly associated with individuals and less so with organisations (in the example above, I've used the organisation' s Legal Entity type as the reciprocal role).

Note: You may have noticed that we are only modelling the case where there is a relationship between exactly two Parties. This is known as a binary relationship. There are also other types of relationships, known as n-ary relationships, that involve many Parties. However, because you can reduce every n-ary relationship to two or more binary relationships (and the fact that binary relationships are more flexible, conceptually cleaner, and easier to understand) we’ll stick with binary relationships in our model.

URI Path Design

The specification includes URI's to create, retrieve, update, and delete (CRUD) relationships.

For example:

POST /individuals/{partyId}/roles

Sample request:

{
  "partyRoleType": "Employee",
  "relatedPartyId": "123e4567-e89b-12d3-a456-426655440000",
  "relatedPartyRoleType": "Employer",
  "relationshipType": "Employment"
}

Metadata

The specification includes metadata services that you can use to discover information about the classifcation schemes and values used by the API:

metadata

References: