Skip to main content

Resource associations

An association describes the relationship between two resource entities. It can be represented as a triplet composed of a left-hand side (LHS) entity, a relationship, and a righ-hand side (RHS) entity.

LHS Entity  ->  relationship  ->  RHS Entity

The following terms are used to describe associations throughout the documentation.

  • belongs to: many-to-one or one-to-one relationship; foreign key is on the LHS
  • has many: one-to-many relationship with zero or multiple instances of the associated entity; foreign key is on the RHS
  • has one: one-to-one relationship with at most one instance of the associated entity; foreign key is on the RHS

Association constraints​

Associations might be mandatory, in which case they are underlined like so:

  • belongs to: mandatory relationship

The most common association is belongs to, which when mandatory establishes a necessary dependency of the LHS entitiy on the RHS entity. For instance, a subcompartment must belong to a forest operation which in turn must belong to a forest property. One cannot create a subcompartment without having created beforehand the corresponding forest operation and its forest property.

In addition, some associations might be polymorphic, in which the RHS instance is of a given entity among several. Polymorphic associations are named and its possible entites are listed between curly braces {}, like so:

  • belongs to: polymorphic name { Entity A | Entity B }

Contraints on the properties of the LHS entity are indicated between parentheses (contraint).

To indicate that a property of the LHS instance must have a value so that the association is valid:

  • belongs to: Entity (property=value)

On the other hand, constraints based on properties of the RHS entity are indicated between square brackets [constraint].

To indicate that a property of the RHS instance must have a value so that the association is valid:

  • belongs to: Entity [property=value]

Including associations when retrieving resources​

Including all associations' data for a given set of resources is computationally expensive and often unnecessary. However, minimal association data is often needed to describe a given resource. For this reason, when retrieving multiple or single resources only a summary of the most relevant related associations is included, in the field related_overview of the JSON response.

Only when retrieving a single resource it's possible to recursively expand related resources, which mainly refer to belongs to associations. For this, if supported by the endpoint set the query parameter expand_related to true and the properties marked as Expanded related association in the API specification will be included. Note that when this query parameter is true, the field related_overview is not included.

Reprising the example above, when retrieving a single forest operation by ID, if we set the query parameter to expand_related to true the operation forest property and the owner of the latter will be fully included in the response.

/forest_operations/071503f8-aec0-41fb-969c-d5f31ab325b5?expand_related=true