4.2. Collections

A Collection is an array, gathering instances of PDEF Objects with the same pdef_type.

4.2.1. Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "pdef_id": "c8f97b56-...",
  "pdef_type": "pdef",
  "pdef_version": "2021-12",
  "bare_pipes": [
    { "pdef_id": "e995ecce-...", "pdef_type": "bare_pipe" },
    { "pdef_id": "35d74462-...", "pdef_type": "bare_pipe" },
    { "pdef_id": "95bdf3f2-...", "pdef_type": "bare_pipe" }
  ]
}

The valid PDEF Document above reports a bare_pipes collection containing three instances of BarePipe (FV) PDEF Objects. To simplify the example above, the other members of those objects are omitted.

4.2.2. Documentation

Collections are optional. There can be none, one or several distinct collections in a valid PDEF JSON Document.

There cannot be two bare_pipes collections in the same PDEF Document. Like any JSON member, collections must be unique.

Collections are members of the root PDEF Document. There is a unique member for each collection. They are declared by the plural of the pdef_type of the object they refer to, eg bare_pipes. Collections bear an s plural mark in the variable name for clear distinction between the object pdef_type and the actual collection variable containing those objects. As a result of this convention, sometimes the collection variable name is not grammatically sound, eg sensor_datas.

For a complete list of the possible collections, refer to the PDEF Schema Section.

Inside the collection arrays, a record is created for each instance. The schema of each object is provided in the PDEF Objects Section.

Note

This design was selected by the partners other an alternative design where all objects could be stored at the root level, directly in the PDEF Document.

The reasons for this choice are:

  • It facilitates reading by humans. Collections act like chapters in the JSON document.

  • it allows splitting of a PDEF Dataset in several PDEF Document more convenient and structured. For example, a pipeline.json file can be dedicated to Pipeline (FV) collection, a bare_pipe.json file to BarePipe (FV) collection and so on.

  • the parser has a direct access to collections. This avoids having to parse and read the entire document to sort the objects per pdef_type.

  • it allows partial loading and parsing of a large PDEF Dataset.