1. Quick Start

This section provides a quick start-up guide.

The most basic usage of PDEF is demonstrated. A simplified PDEF Dataset is written “by hand” as a valid PDEF JSON Document. The PDEF Schema is used to guide the user on how to write and structure the PDEF JSON Document.

Note

This page is provided for the purpose of helping unacquainted users to get started. In practice, the typing work described below is automated by scripts and applications.

Note

A schema description is available in section PDEF Objects where notions of “FV” and “PV” are described.

1.1. Installation

To read and edit JSON document, it is recommended to use a text editor that features syntax highlight, such as Visual Studio Code.

Most modern text editor will support JSON schema with type-hinting and validation. With Visual Studio Code, it will be the case.

For a list of editors that support JSON-Schema, check the relevant ressource documentation.

1.2. Creating a PDEF JSON Document

Let us create a JSON file to write a JSON Document which will contain our test PDEF Dataset. The file is named test.json, and can be downloaded here.

To enable the text editor to find the JSON Schema, the URL of the PDEF JSON schema can be provided as an optional $schema member.

The following lines are typed into the test.json file and the file is saved.

 {
 "$schema": "http://pdef.io/html/downloads/2023-12/pdef_schema.json",
 }

From that point, the text editor will hint the user with the variables everywhere within the PDEF Schema. The members can also be found from the documentation of the root PDEF Document.

The required variables pdef_id and pdef_type are created. Note how an UUID version 4 string is used as pdef_id. UUI v4 are random strings which can be automatically generated using code. They can also be obtained online.

 {
     "$schema": "http://pdef.io/html/downloads/2023-12/pdef_schema.json",
     "pdef_id": "14474720-db23-453a-b9c0-6a9fc9b03ef3",
     "pdef_type": "pdef"
 }

At the root of the JSON PDEF Document lies the Collections. They are records of the various instances of the PDEF Objects.

1.3. Creating the first Project (FV) collection

In this example, a unique project is reported. Still, a projects collection is added to contain this data. Collections are like tables of object instances of the same pdef_type (project in this case).

A new Project (FV) object is created inside this collection, and the members are typed.

The pdef_id will be the unique id for this project and will serve for referencing other objects. In this example, we will assign the value project_1 to pdef_id for our project object. A better practice is to use UUID version 4 for pdef_id

Again, if type-hint is not enough, the structure is described in the Project (FV) object documentation.

Note

Note how the IDE will highlight the mistakes: in the example below, a number was used for the block member of project, whereas the JSON Schema requires a string of characters. The mistake is spotted and reported to the user.

Note

While typing the country member, one can note the enumeration of countries. This happens whenever the JSON Schema only allows for some specific keywords.

The project members can then be written.

The related_pipeline member is a Relations member. For the time being, it is written as an empty array.

{
  "$schema": "http://pdef.io/html/downloads/2023-12/pdef_schema.json",
  "pdef_id": "14474720-db23-453a-b9c0-6a9fc9b03ef3",
  "pdef_type": "pdef",
  "projects": [
    {
      "pdef_id": "project_1",
      "pdef_type": "project",
      "meta_data": {},
      "additional_data": {},
      "name": "Begonia",
      "country": "Angola",
      "block": "Block 15",
      "field": "Begonia",
      "operator": "Total E&P",
      "related_pipeline": []
    }
  ]
}

Once completed, the PDEF JSON Document should look like:

This principle is then repeated throughout PDEF for all the Collections of PDEF Objects.

1.4. Adding the Pipeline (FV) collection

The pipeline collection will record the instances of the Pipeline (FV) object. In this example, a unique simplistic pipeline is added to the pipelines collection.

Except for the required members pdef_id and pdef_type, only the design_life optional member if added. Note how the 15 years Duration is specified.

[
  {
    "pdef_id": "pipeline_1",
    "pdef_type": "pipeline",
    "design_life": { "unit": "y", "val": 15 }
  }
]

And finally, the relation between this instance of pipeline and the project is created. This is done by adding the relevant relation in the pipeline member of project_1. Mechanisms used for Mapping Relations in PDEF are specified in the schema and can be found in the documentation.

The completed file is now a valid JSON PDEF Document which can be exchanged with a partner.