Reference Data Holder

_{Published: 06 July 2025}

Known Uses

This pattern is frequently used within both the Dutch government and the Dutch energy sector domains. Examples:

• ‘Mijn Aansluiting’ offers an online platform facilitating communication between contractors, grid operators, and energy suppliers regarding the administration and maintenance of energy connection points. The platform’s APIs provide access to reference data such as connection types and statuses, adhering to the Reference Data Holder pattern. These APIs are documented and accessible via the DSP Platform Wiki. See the ‘status’ field as example of reference data in the CAPO API (CAPO = Combi Aansluiting Proces Ondersteuning = Combined Connection Process Support) API;
• CBS Content Open Data (OData API): Provides access to all Dutch statistics from CBS (Statistics Netherlands) via OData v4. Many of the datasets (e.g., country codes, region codes, statistical classifications) are reference data: they change rarely, are centrally managed, and are consumed by many systems.
• PDOK Locatieserver (Geocoding, Address, Zip Code, and Place Lookup). PDOK stands for Publieke Dienstverlening Op de Kaart (PDOK), which means public services on the map. This RESTful API allows searching addresses, zip codes, cadastral parcels, municipalities, neighborhoods, and more. It supports autocomplete, reverse geocoding, and direct lookup by text or code.
• RFC 9457 is the standard for error handling in both our domains, and it includes a type field which serves as a reference endpoint.Example: "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#/10.4.1"The type field in the error payload acts as a Reference Data Holder, using a URI to identify a specific error type or validation rule. This follows best practices for reference data, where values are not arbitrary but instead link to authoritative definitions or controlled vocabularies.

Discussion Input

We see reference data as a subset or a foundation of master data, providing structure and classification, while master data contains the business-critical entities that evolve over time.

In the energy sector, we use a structured approach to identify the functional source of a given identifier (MRID). Each MRID includes an additional attribute called identificationScheme, which classifies the identifier using a URI. By leveraging the identificationScheme and a conversion API, it’s also possible to reclassify an MRID. This allows, for example, retrieval of related resource information from another system – where the same resource might be represented by a different MRID.

Example of an EAN MRID classification:

"MRID": {
  "content": "871687110001427844",
  "_identificationScheme": "urn:x-enexis:ecdm:schemes:mrid:connections:ap:e"
}

Both the MRID and Error 9457 type field examples demonstrate a powerful design approach that combines two architectural patterns:

• Metadata Element – provides descriptive context (e.g., what kind of identifier or error it is).
• Reference Data Holder – points to a standardized value or URI for interpretation.

This combination improves consistency, clarity, and interoperability. It ensures that all parties interpret identifiers and errors the same way, using shared vocabularies and references, while adding meaningful context without overwhelming the payload.