• Engineering

Going Open Source

17th May, 2022

As a health insurance company, we deal with data of our customers on a daily basis. This data is by a central ID, the health insurance number (KVNR). The health insurance number accompanies insured persons throughout their lives. It is random and does not contain any personal information.
Because the KVNR is so important, we at vbu.tech have created an open source Java library that encapsulates this ID. The library performs two key tasks:

  1. Validating the KVNR

  2. Providing KVNRs for quality assurance purposes

Point 1 is trivial. The KVNR is validated by checking for the following structure: A leading letter followed by 9 digits and a checksum calculation according to the Luhn algorithm. Background information on the Luhn algorithm can be found in Wikipedia.

Point 2 is an extension by the vbu.tech Platform team. We provide the possibility to use non-valid (unofficial) KVNRs for quality assurance. The issuing offices of the KVNRs do not provide such unofficial KVNRs. If we use valid KVNRs, there is always the risk that we use accidentally use health insurance numbers, which are assigned to a person. To avoid this, we can use our own health insurance numbers that are not valid. In the vbu.tech Platform team, we use KVNRs between Q000000000 und Q000000099.


// Create a non-valid KVNR
final var insureeNumber = new Krankenversichertennummer("Q0000000");

System.out.format("Is test number: %b%n", insureeNumber.isTestNumber());

In this example, a non-valid KVNR is used to create a health insurance number instance. Since this KVNR belongs to our defined test number set, the generating constructor does not throw an exception (ChecksumException). Instead, the isTestNumber() method returns a true as value

Since our Q-number range cannot be used by all users, we have created a service provider mechanism that allows each user to define our own test number range. To create such a custom range the interface TestKrankenversichertennummerValueProvider must be implemented and provided in module-info.java using provides.


package my.own.project;

import tech.vbu.kvnr.spi.TestHealthInsuranceNumberValueProvider;
import java.util.Set;
import static java.util.Set.of;

public class SimpleTestValueProvider extends TestHealthInsuredNumberValueProvider {
    public Set<String> values() {
        return of("z0000000");

In this example, we create a single artificial KVNR for testing purposes.
In order to use it in your own projects, you have to make it known to the Java module system in the module-info.java file:

module my.own.project {
    requires tech.vbu.krankenversichertennummer;
    provides tech.vbu.kvnr.spi.TestHealthInsuredNumberValueProvider with my.own.project.SimpleTestValueProvider;

Further information

The vbu.tech health insurance number library is implemented without any further dependencies. It is kept very small and is used by us as a kind of shared kernel. That means we guarantee full backward compatibility within the version scheme (see README.adoc of version 1.0).

In your own projects you can include the library using Maven or Gradle Dependency from Java 11 onwards.

Since we are convinced of the paradigm Public Money, Public Code, we have made the library available under the liberal GNU Lesser General Public License version 3 or higher.

Link: https://gitlab.com/b3891/vbu-krankenversichertennummer-jvm

Sascha Kohlmann
Senior Backend Developer