4.4.2. Mapping Relations

Relations are used to interlink objects.

In PDEF, relations are represented based the following objectives:

  • explicitly declared,

  • set within the JSON schema (ie allowed or not),

  • optional.

For example, PDEF allows a relation to be provided between a BarePipe specification BarePipeSpec (PV) and a BarePipe (FV). However, there is no relation allowed between an BarePipe (FV) and a Route (FV). The PDEF JSON Schema specifies what type of relation is allowed.

Relations are represented using two types of design:

4.4.2.1. Nested Object

A Nested Object is an object reported in an array member of another object, possibly alongside other objects of the same pdef_type.

4.4.2.1.1. Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "pdef_id": "f85",
  "pdef_type": "pdef",
  "pdef_version": "2021-12",
  "coated_pipes": [
    {
      "pdef_id": "bd5",
      "pdef_type": "coated_pipe",
      "records_of_coating_layer": [
        {
          "pdef_id": "8e5",
          "pdef_type": "coating_layer"
        },
        {
          "pdef_id": "27d",
          "pdef_type": "coating_layer"
        }
      ]
    }
  ]
}

The example above shows two instances of CoatingLayer objects (8e5 and 27d), embedded in the instance bd5 of CoatedPipe (FV).

4.4.2.1.2. Principles

An Nested Object relation representation design is selected:

  • when the number of relation is rather limited,

  • when the Nested Object will always be reported with its parent object.

To facilitate the reading, parsing and understanding, the array members dedicated to wrap nested objects start with records_of_ consistently.

Note

This is the case in the example above. An instance of CoatedPipe (FV) as only a few CoatingLayer. A CoatingLayer will always be reported with its related CoatedPipe (FV). A CoatingLayer collection at the root of the PDEF JSON Document would not make much sense, because not reported on a stand-alone basis.

4.4.2.2. Reference Relations

Some objects are related to several over objects and re-used in various places in the model.

In such a case, the relations are represented in JSON using a primary key referencing pattern. The object pdef_id is used as primary key and reported in an array. This allows to specify one-to-one, one-to-many, many-to-one and many-to-many relations using a unique consistent pattern.

4.4.2.2.1. Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "pdef_id": "f85",
  "pdef_type": "pdef",
  "pdef_version": "2021-12",
  "projects": [
    {
      "pdef_id": "j76",
      "pdef_type": "project",
      "related_pipeline": ["bd5", "g78"]
    }
  ],
  "pipelines": [
    { "pdef_id": "bd5", "pdef_type": "pipeline" },
    { "pdef_id": "g78", "pdef_type": "pipeline" }
  ]
}

In the example above, a reference relation is inserted into Project (FV) j76 to reference two instances of Pipeline (FV) objects, namely bd5 & g78.

4.4.2.2.2. Principles

A reference relation is created by adding a dedicated member:

  • The key starts consistently with related_, generally concatenated with the value of the pdef_type of the referenced object class, eg related_pipeline. However, if the related object can be of various pdef_type, this convention cannot be followed.

  • The value is an array, containing the pdef_id of the referenced instances. If the relation calls for a unique reference, then the array has maximum one item.