Designing the Vereign Data Schema


Vereign Data Schema

Requirements & Considerations


Supporting organisations in Vereign requires certain capabilities in our handling of data schemata - which need to happen alongside our changes to individual data schemas.

Challenges include:

  • Secretary / Delegation Function: A person in an organisation has a permanent (secretary/assistant) or temporary (vacation/illness) stand-in empowered to read and respond to mail, in some cases even with power of attorney to sign contracts;

  • Inheritance of relationships based on function, e.g. the senior account representative for a customer will typically inherit the history of this account with previous account managers;

  • Mass administration of users, e.g. on-boarding 500 new users for Vereign, often automated in some ways;

  • Functional / shared mailboxes, like a mailbox for all incoming sales mail, or a mailbox for the support team. These mailboxes are shared among a changing set of people, sometimes with rotation of responsibilities;

  • Mailing groups/lists, where one mail is sent to a single address, but delivered to dozens, sometimes hundreds or thousands of email addresses, some of which may themselves be mailing lists in their own rights. Some systems include sub-groups of such mailing groups, e.g. Google Groups.

All these functions are most commonly administrated with Microsoft Active Directory, the Lightweight Directory Access Protocol (LDAP) or G-Suite Admin. Typical examples for mailing list / mailing group software includes GNU Mailman, Discourse or Google Groups.

All of these are orthogonal to organisational structure, and in the case of mailing groups/lists also apply to individuals.

Organisational structures include complexities such as

  • Incorporated entities in certain jurisdictions with certain authorities;

  • Incorporated sub-entities in the same or other countries;

  • Organisational units with unlimited iteration depth (e.g. there are sub-sub-sub-sub-sub-units and the number of “subs” is a function of organisational size and design);

  • Staff with various roles and titles that evolve over time;

  • Staff that can be legally connected to the sub-unit of a sub-entity in a different country, yet still hold a formal role, function and title with the original organisational entity. e.g. the Head of Development of Vereign AG (incorporated in Zug, Switzerland) has an employment contract with Vereign Labs Ltd (incorporated in Plovdiv, Bulgaria).

Which leads to a picture looking something like this:

Personal Identity within an Organisation

Personal identity within an organisation

  • MUST NOT give the organisation full access to all personal information of the employee;

  • MUST take into account the fluidity of changing roles, promotions and demotions, on- and off-boarding of staff in any organisation.

Thus the connection of individuals to / inside an organisation MUST be based on PROFILES containing the information of a personal identity that is relevant to and appropriate to share with the organisation, e.g. name, birth date, personal email, address.

Most of that information will however typically NOT be shared with anyone but the Human Resources (HR) department inside the organisation, and very rarely with anyone outside the organisation.

So the PROFILE of the PERSONAL IDENTITY goes toward creating a PERSONAL IDENTITY AS PART OF THE ORGANISATION, which inherits (think: “Reverse CRM”) the shared fields from the PERSONAL IDENTITY, plus attributes that come from the ORGANISATION itself, such as email address, title, function, corporate communication channels and so on.

Contracts and official communication between the employee and the company, such as working contracts or salary slips must therefore be understood as interactions between the responsible functional unit of the organisation and the working profile of the personal identity of the employee.

On the company side, those interactions ultimately belong to the organisational unit responsible for them, in this case HR. So when the person who handled them leaves they can be taken over by the next person. In many organisations such files / interactions are shared among all the people tasked with their maintenance, so that interactions should immediately be stored with the organisational unit - and the people with the requisite roles should have access to them.

Shared mailboxes / functional addresses

When responding as part of a functional / shared mail box, the party on the other side is most interested in the response being a legitimate representation of the organisation. Sometimes it should be accompanied by personal information about who specifically responded - but very often that information should not be visible to anyone outside the organisation.

Shared mailboxes & functional addresses (“”) will therefore often have dedicated, specific profiles that are organisationally defined and available to be used for people with personal organisational attributes giving them the requisite role.

Personal Identity

A personal identity should be useful and complete for all use cases people would like to make use of Vereign for and must be extensible. Any personal identity must be secure from third party access, and interact with other parties only through profiles.

Mailing lists / groups

Using a profile with a mailing list / group is an explicit agreement to share this profile with all current and future members of this group. All participants of a list should have access to

  • verified sender identity

  • message status (sent, read, …)

Links between participants should be established when they respons / become active, i.e. have chosen a profile for interaction with the group.

Inheritance / escrow

Inheritance and escrow are the only exceptions to the principle of an identity not being accessed by anyone but the person themselves. TBD

Relationship to existing Directory Services

There are many implementations of data schemas, and like standards, inventing yet another one is a bad idea. It increases the amount of work required for integration with third party systems and the barrier to integration for others into Vereign.

The most common format for data schemas is based on LDAP, which is also the basis of Microsoft Active Directory. And when on-boarding an organisation with Vereign, we would just like to be able to DYNAMICALLY LINK VEREIGN WITH THE DIRECTORY SERVICES ALREADY IN USE.

That way, companies do not need to change their administration process for on-boarding or phasing out employees, and re-training is limited. Also, the directory service already contains information about organisational structure, as well as rights, roles and responsibilities along with mailing lists / groups and functional addresses / shared folders.

For deployments with medium to large corporations using a directory service, Vereign must be understood as a CLIENT to their existing directory service which dynamically creates the entities and relationships as required based on the information in the directory service. This includes organisations in the Google App Suite, which are using the G-Suite Admin.

Technically this breaks down to

  • A connector towards LDAP / ActiveDirectory;

  • A connector towards G-Suite Admin.

Organisations without directory service

Many organisations do not use directory services, and take a manual approach to on-board and phase out employees across a set of systems. Because this is labour intensive and error prone, it’s typically only small organisations using this approach - but they may still choose to use Vereign.

These are the kinds of organisations we want to have a limited set of domain administration functionality for, such as

  • Create/modify/remove user;

  • Create/modify/remove sub-unit;

  • Create/modify/remove organisational profiles.


Properties of an identity, such as name, pictures, telephone numbers, citizenship, passport ids, birth date can be verified as part of a wide array of services and online identities. Our data schema must meet the following requirements:

  • Each property must be verifiable individually, e.g. the name must be possible to verify independently from the birth date, and by different parties;

  • Each property must be able to carry multiple verifications, e.g. the name could be verified by a bank, and also by using services such as CBFS or PXL vision;

  • Each verification must be capable of carrying an expiry date, e.g. the passport number cannot be valid longer than the passport itself, some uses require occasional re-verification;

  • Verification must be capable of hiding the identity of the verifying party, e.g. Credit Suisse might not want to disclose they verified a certain person to UBS, as that would give away them being a customer that could be poached;

  • Hiding the identity of the verifying party is not always desirable, e.g. PXL vision and CBFS each make their living by providing identity verification. It is part of their business model to advertise these services and link a verification to their own records as added value, plus they are part of the revenue sharing ecosystem of Vereign;

  • Verification should be able to express levels of verification, e.g. automatic confirmation via code is a different level for email or using social media accounts to verify names is a different level from reading out governmentally issued identity documents, purely automated verification provides a different level of verification than human interaction.

Verification information in other words, must be an array on each individual property containing

  • Verifying party, potentially using W3C DID based Zero Knowledge Proof to obfuscate the identity of the verifying party while ensuring independent, decentralised trust into the verification itself; potentially this could include an element of mutual disclosure of identity to one another, e.g. UBS and Credit Suisse agree to become visible to one another when the same customer on-boarded at one is opening an account at the other;

  • Signature on the verified data set;

  • Flags specifying information on verification methodology: governmentally issued, social media, automated, human;

  • Date of verification;

  • Date of expiry of signature;

  • OPTIONAL: URL for revocation check on signature of verifier;

NOTE: This is still drafted into the rough, feedback extremely welcome.


The G-Suite Admin SDK is a RESTful, well documented API for handling this kind of data. It is not too dissimilar to LDAP / Microsoft Active Directory in its fields and their meaning, and has an existing set of tools integrated against it.

By basing our data schema on this specification as closely as possible, building our external API for third party integration and providing validation on it, and by integrating our organisational module against the G-Suite Admin for organisations that use Google for their communication needs, we reduce the barried to integration across the board.

Integration into Microsoft Active Directory / LDAP can then take the form of a bidirectional connector.

Extension of G-Suite Admin SDK Specification

The specification does not cover everything, e.g. organisations are called “Customers” and do not map to legal entities in the same way Vereign would like to link to commercial registration, including the URL of the live entry of the organisation.

The specification also has no understanding of verified identity properties, nor of live connections between profiles. Users also do not have properties like id card, passport and such.

These are the parts we will need to specify ourselves as extensions to the existing specification. The result will be a Vereign Admin API.

Issues coming to my mind

not particularly structured

An organisation has to be initiated by an individual. A work profile of an individual has to be initiated either by a function’s or another individual’s work profile. The establishing of work profiles will be the initial path of user registrations and therefore must involve an even shorter (i.e. pre-filled fields) onboarding for the relevant individuals, while unlocking the benefits for the individual (i.e. default profiles, etc.) concurrently.

An individual might have several work profiles.

Individuals are not charged for the live connections they entertain, only organisations are. Thus, the functional profile establishing the individual’s work profile might end up to be the identifier for the charging mechanism, because several individuals’ work profiles might have the same outside contact and should not be charged several times.

Credits apply and deplete differently per profile. An individual’s work profiles of the same organisation (including its sub-units) cost 5 credits in total, while his/her private profiles cost 1 credit in total per day. An individual with several work profiles will be charged by organisational affiliation.

Credits should be able to be sent to any profile, no matter if work or individual. However, similar to airline miles, receiving credits into one’s work profile cannot be retrieved or forwarded unless specifically enabled by the organisation’s administrator.

An individual setting up an organisation and paying per function-work profile will be able to play the system by transferring / storing credits in his/her individual profile where credits are depleting slower. This is relevant in case the same individual (e.g. an entrepreneur) would like to use the service intermittently only.