Skip to main content

GIR Basisdata Messages

Version: Processdescription v1

Conceptual Model​

This Conceptual Data Model section provides an overview of the underlying structure of the register. It explains the key concepts and relationships between different data elements and sets the foundation for the rest of the architecture. This section is designed to provide a high-level understanding of the system’s data architecture, making it a valuable resource for both technical and non-technical readers.

Conceptuel model
Figuur: Conceptuel model

Process​

The idea behind the Building Installation Register (GIR) is that installations and components are recorded in a single register. With information from that register, you can take further steps to retrieve more details about these installations and components.
An example: through the register, you can query the relevant ETIM class of a product within a specific installation. Using this key, the product characteristics can be retrieved from a datapool (for example, 2BA).

From a technical perspective, two types of parties can be distinguished in the GIR: parties that register and parties that retrieve data. For retrieving parties, POST and GET calls are available. For a party that wants to register, a few additional steps are important for implementation. A standard POST call is available to submit a registration to the register (see API documentation), but the software must know a few things beforehand to perform a correct registration:

Step 1: Is the product registered in the datapool (happy flow) or not (unhappy flow)?

Step 2: The ETIM class must be included in the registration to the GIR. This is enforced in the schema, but it can be combined with step 1. By checking whether the product is registered in a datapool, the correct ETIM class can also be retrieved.

The two scenarios are shown schematically below:

Happy and unhappy flow
Figure: Happy and unhappy flow

Product Databases​

As mentioned, a two-step approach is possible from within the GIR. Product information itself is not stored in the GIR systems but is available through other sources such as product databases. From the conceptual model: Components refer to Products. A Component is an instance of a Product that has been installed as part of an Installation.

In principle, it is also possible to retrieve installation-related data from other sources. Product information is accessible via (public) sources based on known GTIN and ProductCode/GLN combinations. However, this approach is less suitable for automated processing.

Generic product data will never be stored directly in the GIR. Only the identification code and specific information related to the component/product are recorded.

Key Structures GIRBasisdata​

Installation​

An Installation is a collection of Components that together perform a specific function at a Locations (e.g., a Residential Unit). The Installation serves as the core entity to which all other entities within the registry can be linked.

An Installation cannot be identified by a generic manner. Instead, it is defined by the individual registering the Installation. If no ID is provided, the system will automatically assign one (GUID). However, users have the option to specify an ID, with GIAI being the preferred choice.

Currently, Installations are classified based on their function using the NL-SfB system. This classification helps determine the type of Installation being registered and is also used to identify applicable regulations for future applications.

Component​

A Component is a part of an Installation and represents an instance of a Product. For example, a Boiler Component may be part of a Central Heating Installation.

Typically, a Component belongs to a single Installation, and most Installations consist of just one Component. However, some Installations comprise multiple Components, such as cascading systems. Conversely, a Component may also be associated with multiple Installations. For example, a Smart Energy Meter Component could belong to both a Solar Energy Installation and a Gas-Powered Heating Installation.

Components are identifiable in the physical world through a unique serial number present on the Component. The preferred order of identification is as follows:

SGTIN – A unique serial number assigned to the manufacturer by GS1. Serial Number – A unique (possibly non-standardized) tuple provided by the manufacturer User-Applied Number – A number assigned by the Registrant and physically written on the Component.

This number is a critical feature in the system because it can be found in the real world, serving as a quick entry point to locate the Component and its associated Installation.

A Component should never contain generic Product information about the associated Product. However, certain seemingly generic details may be configured for each specific Component. In such cases, this information must be applicable relevant to the Component specifically. The info is preferably stored using ETIM Features in a key-value set.

Product​

A Product is an item manufactured by a Manufacturer. When a Manufacturer creates a Product, individual Units are produced. Once installed, such a Unit is registered as a Component within the GIR. Products typically have a Brand, Model, and Version.

A Product is identified by a GTIN issued by GS1. Since these numbers are managed by GS1, they are globally unique. However, some manufacturers may choose not to use a GTIN. In such cases, they assign their own ProductCode, which is not guaranteed to be globally unique. To ensure unique identification, the manufacturer’s GLN is added. The combination of GLN and ProductCode creates a globally unique identifier.

Products are classified using an ETIM Class, which defines the type of Product. This Classification is carried over to the Component level in the GIR and must remain consistent. ETIM Classes include ETIM Features, which describe the specific characteristics a Product may have. Each feature can have a designated value for a given Product. While this information enhances the registration in GIR, it is not stored in the GIR itself but in dedicated Product Databases.

Manufacturer​

The Manufacturer of a Product plays a role in the GIR as it contributes to product identification, particularly when a GTIN is not available and a ProductCode is used instead.

Locations​

A Location describes where the Installations is located. Only a reference to the location is stored in GIR. There are plenty of ways to describe the location. For instance GeoCoords, Postalcode and the Kadasters Verblijfsobject. Please that currently only one type of reference is supported, being the Residential Unit (Kadaster Veblijfsobject).

The data model must allow for multiple types of references to be added. In the near future GLN will be added.

Residential Unit (Kadaster Veblijfsobject)​

De locatie van een Installatie wordt in het GIR als eerst bepaald aan de hand van het Verlijfsobject zoals dit is vastgelegd in het Nederlands Kadaster. Ieder Verblijfsobject heeft een uniek nummer (VBO_ID). Een Verblijfsobject is terug te leiden aan een Adresseerdbaar Object en Plaats.

Location GLN​

Een aantal Locaties is nader gedefinieerd met behulp van een Global Location Number. This globally unique nummer wordt uitgegeven door GS1 en kan worden toegekend aan een specifiek locatie die mogelijk nog specifieker is dan het Verlijfsobject.

Classification Systems​

Met behulp van Classificatie Systemen kunnen Installaties en Componenten algemeen groeperen en identificeren. Het soort Instalaltie of het soort Component bepaald wat voor wetten en regelgeving van toepassing zijn. Ook het soort eigenschappen dat een component heeft kan worden vastgesteld aan de hand van de classificatie.

Installation Classification: NL-SfB

Installations are elements that serve a function within a building. A suitable classification model for these elements is NL-SfB. Every Installation in the GIR is classified at Element Level 3 according to the NL-SfB system.

Component Classification: ETIM Classes

At the Component level, ETIM Class classification is used. The classification is inherited from the Product that has been installed.

Logical Data Model​

See Semantic Treehouse documentation for the messagemodel which is used in de schema's for building the Open API Specifications

API Calls​

Information about installations in buildings is exchanged using API messages. These messages are in REST format and are described based on DICO messages as defined by Ketenstandaard. This section outlines the DICO format that must be used. The full API documentation can be found in Semantic Treehouse.