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. Keep in mind 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
note

Expanded related associations are not available on listing endpoints. However, in the API documentation of listing endpoints, properties marked as "Expanded related association" will be shown on the response samples because the serialization is the same for retrieving multiple or single resources and ReDoc by default shows optional attributes of response schemas. It was decided that the alternative, only showing required properties, would be too limiting.