Building the datasets

The Equipment data product defines how devices and equipment in a power network are modelled, i.e. the connectivity of the grid (node/breaker). This document explains the structure of the datasets and how instances interact across datasets.

Generate your own mRIDs using UUID4

All JSON-LD examples below are just that; do not reuse mRIDs unless retrieved from the NBNL Object Register.

Overview

Each System Operator provides a dataset containing the connectivity for a specific part of the electrical grid (HV, MV and LV). The High Voltage (HV) dataset defines exchange points between TSO and DSOs. This dataset is also referred to as the boundary dataset.

A singular dataset (with the exception of the boundary dataset) does not validate against the provided SHACL on its own; both boundary dataset and system operator specific dataset must be validated together.

Metadata

Each dataset requires metadata to keep track of issuer, issuance date, schema and dependencies.

Metadata is not validated against the SHACL schema, but do not omit these fields!

"@id": "urn:uuid:2d3088c1-2b9a-4cbc-84fa-c0670e0e8ecc", (1)
"dcterms:issued": {
  "@value": "2025-12-05T12:34:567Z", (2)
  "@type": "xsd:date"
},
"dcterms:publisher": {
  "@id": "urn:uuid:4f74c8e2-adb5-4815-9607-eb00fb6a0d55",
  "dcterms:title": "Liander" (3)
},
"dcterms:conformsTo": [
  {
    "@id": "https://modellen.netbeheernederland.nl/nbnl-equipment/1.0" (4)
  }
],
"dcterms:references": [
  {
    "@id": "urn:uuid:4562ba86-b5e0-470b-8e36-dae55428d77f" (5)
  }
]

The following information is required:

unique identifier for this dataset. Use a generated UUID;
issuance data, start of the validity period for this dataset;
publisher of the dataset. Use the mRID/name from the NBNL Object Register;
schema to validate the dataset against. Verify usage of the correct version;
any datasets this dataset is dependant on. For any non-boundary datasets, this is the @id of the boundary dataset referred to.

TSO High Voltage (Boundary) Dataset

Each dataset contains a singular cim:GeographicalRegion as its root:

{
  "@id": "urn:uuid:3061d9bc-a20e-4b72-85b7-042c731f86be",
  "@type": "cim:GeographicalRegion",
  "cim:IdentifiedObject.mRID": "3061d9bc-a20e-4b72-85b7-042c731f86be",
  "cim:IdentifiedObject.name": "NL"
}

Added to the cim:GeographicalRegion is a cim:SubGeographicalRegion, which defines the System Operator License Area:

{
  "@id": "urn:uuid:2128cb2f-9425-4cf7-9462-9fd59e06542d",
  "@type": "cim:SubGeographicalRegion",
  "cim:SubGeographicalRegion.Region": {
    "@id": "urn:uuid:3061d9bc-a20e-4b72-85b7-042c731f86be"
  },
  "cim:IdentifiedObject.mRID": "2128cb2f-9425-4cf7-9462-9fd59e06542d",
  "cim:IdentifiedObject.name": "TenneT"
}

Refer to other instances through their @id (cim:IdentifiedObject.mRID)

The License Area is a container for all cim:Substation-s in the dataset:

{
  "@id": "urn:uuid:755de658-5567-4b65-85bd-f6d3cf41d992",
  "@type": "cim:Substation",
  "cim:Substation.Region": {
    "@id": "urn:uuid:2128cb2f-9425-4cf7-9462-9fd59e06542d"
  },
  "cim:IdentifiedObject.mRID": "755de658-5567-4b65-85bd-f6d3cf41d992",
  "cim:IdentifiedObject.name": "Station Arnhem 150"
}

A cim:Substation is a HS/MS Hoogspanningsstation, which acts as a container for cim:VoltageLevel-s and the eu:BoundaryPoint-s.

Voltage Level

{
  "@id": "urn:uuid:8038196f-375a-4eb1-94dd-5269a856aad3",
  "@type": "cim:Voltage",
  "cim:Voltage.multiplier": {
    "@id": "cim:UnitMultiplier.k"
  },
  "cim:Voltage.unit": {
    "@id": "cim:UnitSymbol.V"
  },
  "cim:Voltage.value": {
    "@value": 150.0,
    "@type": "xsd:float"
  }
},
{
  "@id": "urn:uuid:3d2d86e6-be41-4259-a55f-b3ed254b35a9",
  "@type": "cim:BaseVoltage",
  "cim:BaseVoltage.nominalVoltage": {
    "@id": "urn:uuid:8038196f-375a-4eb1-94dd-5269a856aad3"
  },
  "cim:IdentifiedObject.mRID": "3d2d86e6-be41-4259-a55f-b3ed254b35a9",
  "cim:IdentifiedObject.name": "Hoogspanning (150 kV)" (1)
},
{
  "@id": "urn:uuid:69e74dbd-b68a-4e2b-8cf7-da98891de6a1",
  "@type": "cim:VoltageLevel",
  "cim:VoltageLevel.BaseVoltage": {
    "@id": "urn:uuid:3d2d86e6-be41-4259-a55f-b3ed254b35a9"
  },
  "cim:VoltageLevel.Substation": {
    "@id": "urn:uuid:755de658-5567-4b65-85bd-f6d3cf41d992"
  },
  "cim:IdentifiedObject.mRID": "69e74dbd-b68a-4e2b-8cf7-da98891de6a1"
}

At the time of writing, transformers, busbars, switches and bays are not part of the HV dataset

A cim:VoltageLevel has a cim:BaseVoltage (1), specifying the high voltage transmission level. cim:BaseVoltage is managed by the NBNL Object Register. The cim:VoltageLevel is associated with a cim:Substation. It’s common practice to add a cim:VoltageLevel for each transformer on the transmission side of the cim:Substation.

Boundary Point

{
  "@id": "urn:uuid:d39090b1-58aa-446b-9551-4c6188aa7d0f",
  "@type": "eu:BoundaryPoint",
  "nl:IdentifiedObject.europeanArticleNumberEAN": "8000123456789012",
  "eu:BoundaryPoint.fromEndIsoCode": "NL",
  "eu:BoundaryPoint.fromEndNameTso": "TenneT",
  "eu:BoundaryPoint.toEndIsoCode": "NL",
  "eu:BoundaryPoint.toEndNameTso": "Liander",
  "cim:IdentifiedObject.mRID": "d39090b1-58aa-446b-9551-4c6188aa7d0f"
},
{
  "@id": "urn:uuid:f0c14f64-3aa3-44ae-b858-18d6a75dc72a",
  "@type": "cim:ConnectivityNode", (1)
  "cim:ConnectivityNode.ConnectivityNodeContainer": {
    "@id": "urn:uuid:69e74dbd-b68a-4e2b-8cf7-da98891de6a1" (2)
  },
  "eu:ConnectivityNode.BoundaryPoint": {
    "@id": "urn:uuid:d39090b1-58aa-446b-9551-4c6188aa7d0f" (3)
  },
  "cim:IdentifiedObject.mRID": "f0c14f64-3aa3-44ae-b858-18d6a75dc72a"
}

Defining a Boundary Point between TSO/DSO is achieved by adding one or more cim:ConnectivityNode-s (1) to a specific cim:VoltageLevel (2) and associating the cim:ConnectivityNode to a cim:BoundaryPoint (3).

Repeat all steps above to create instances for all net functions in the grid and associated where required. For a full example, see Example High Voltage (HV) JSON-LD instance data.

DSO Medium Voltage (MV) Dataset

The DSO MV dataset builds on the boundary dataset by adding cim:PowerTransformer-s and cim:VoltageLevel-s for each distribution transformer. Each Distribution System Operator provides a dataset for its own License Area, associated to the boundary dataset.

a DSO dataset does not validate against the SHACL, the boundary dataset is also required!

Power Transformer

{
  "@id": "urn:uuid:efeba515-547b-4c1a-8cd0-4cbc5f714283",
  "@type": "cim:PowerTransformer", (1)
  "cim:Equipment.EquipmentContainer": {
    "@id": "urn:uuid:755de658-5567-4b65-85bd-f6d3cf41d992" (2)
  },
  "cim:IdentifiedObject.mRID": "efeba515-547b-4c1a-8cd0-4cbc5f714283"
},

Add all cim:PowerTransformer-s (1) on the distribution side of the cim:Substation (2) from the boundary dataset. Do not create an instance of the cim:Substation from the boundary dataset, rather refer to the mRID defined in the boundary dataset for the cim:Substation.

{
  "@id": "urn:uuid:9cc70c8a-f352-4ad5-8743-6295e2800c63",
  "@type": "cim:Terminal", (2)
  "cim:Terminal.ConnectivityNode": {
    "@id": "urn:uuid:f0c14f64-3aa3-44ae-b858-18d6a75dc72a" (3)
  },
  "cim:IdentifiedObject.mRID": "9cc70c8a-f352-4ad5-8743-6295e2800c63"
},
{
  "@id": "urn:uuid:3c052f67-8180-44a9-8bb6-f13b75e94f02",
  "@type": "cim:PowerTransformerEnd", (1)
  "cim:PowerTransformerEnd.PowerTransformer": {
    "@id": "urn:uuid:efeba515-547b-4c1a-8cd0-4cbc5f714283"
  },
  "cim:TransformerEnd.endNumber": 1,
  "cim:TransformerEnd.Terminal": {
    "@id": "urn:uuid:9cc70c8a-f352-4ad5-8743-6295e2800c63"
  },
  "cim:IdentifiedObject.mRID": "3c052f67-8180-44a9-8bb6-f13b75e94f02"
}

For the primary transformer winding, add a cim:PowerTransformerEnd (1) and cim:Terminal (2). The cim:PowerTransformerEnd is associated with both a cim:Terminal and cim:PowerTransformer. Associate the cim:Terminal from the primary cim:PowerTransformerEnd with the cim:ConnectivityNode defining a cim:BoundaryPoint (3) from the boundary dataset.

{
  "@id": "urn:uuid:4d4b29be-1386-45e1-acc3-b86cfab83c94",
  "@type": "cim:Terminal",
  "cim:Terminal.ConnectivityNode": {
    "@id": "urn:uuid:13232d25-3dd8-46f1-ad21-a77b0458648e"
  },
  "cim:IdentifiedObject.mRID": "4d4b29be-1386-45e1-acc3-b86cfab83c94"
},
{
  "@id": "urn:uuid:3a926964-8420-4c57-8a1d-8ac87193b0c6",
  "@type": "cim:PowerTransformerEnd",
  "cim:PowerTransformerEnd.PowerTransformer": {
    "@id": "urn:uuid:efeba515-547b-4c1a-8cd0-4cbc5f714283"
  },
  "cim:TransformerEnd.endNumber": 2,
  "cim:TransformerEnd.Terminal": {
    "@id": "urn:uuid:4d4b29be-1386-45e1-acc3-b86cfab83c94"
  },
  "cim:IdentifiedObject.mRID": "3a926964-8420-4c57-8a1d-8ac87193b0c6"
}

Create an cim:VoltageLevel instance for each cim:PowerTransformer, following the instructions from Voltage Level. Associate the cim:Terminal for the secondary (and up) winding(s) for the cim:PowerTransformerEnd with the cim:ConnectivityNode in the create cim:VoltageLevel. This explicitly associates a cim:PowerTransformerEnd with a specific cim:VoltageLevel and cim:BaseVoltage.

For a full example, see Example Medium Voltage (MV) JSON-LD instance data. Note that the MV example data includes a copy of the boundary dataset for validation purposes. Do not replicate this behaviour for datasets created by a System Operator.