Authors: Julien Vanwambeke, Gaia-X, Functional Architect and Alexis Deprez, Full-stack Developer
Introduction
Christmas time 🎄 is over now and almost all the little ones were writing down their Wishlist letters for Santa Claus 🎅. To do so, they were browsing through paper catalogues selected by their parents, even sometimes pasting images of the expected gifts on their letters 💌.
In the world of Data, it is always Christmas!
Services and Data providers are publishing their offers through catalogues so that consumers can find and browse them!
And here pops Gaia-X adding trust between all these participants!
What is a Gaia-X Catalogue?
First, let us start with some definitions.
A catalogue is “a list of things such as the goods you can buy from a particular company, the objects in a museum, or the books in a library” (Collins Dictionary).
For Gaia-X, a catalogue is to (Gaia-X Architecture Document):
- enable Consumers to find best-matching offerings and to monitor them for relevant changes in the offerings.
- enable Producers to promote their offerings while keeping full control of the level of visibility and privacy of their offerings.
- avoid a gravity effect with a lock-out and lock-in effect around a handful of catalogue instances.
In other words, a Gaia-X Catalogue is a public service, synchronised and federated with the other Gaia-X Catalogue instances, listing Gaia-X Compliant services and data product offerings:
- Providers and their services and data product offerings are Gaia-X Compliant
- The Catalogue provider is following Gaia-X specifications.
- Consumers may have to be Gaia-X Compliant depending on the Catalogue policies.
How to interact with a Catalogue Provider?
As mentioned just above, all the participants gravitating around a Gaia-X Catalogue may have to be Gaia-X compliant.
To do so, they must call the compliance service from a Gaia-X Digital Clearing House (keep in mind each participant can call a different Gaia-X Digital Clearing House as they are all interoperable). In return, each participant will get its Legal Participant Verifiable Credential that will be used to call the catalogue to publish services or to browse services (if required by the Catalogue).
Thanks to the Credential Event Service, each Gaia-X Catalogue is aware of existing Verifiable Credentials generated in the Gaia-X Ecosystem. It can, depending on its own rules, thus attest that the chain of trust is valid and publish a service or provide a list of service providers to a Consumer.
To help the Consumer choose, the list of service providers can be reduced thanks to the Policy Reasoning Engine, filtering criteria, or service composition and Gaia-X Trust indexes can also be added to the shortlist of providers (read our other articles to know more about these two topics!).
Once the Consumer has selected a service offering, it can directly call its provider using the information provided by the catalogue (keeping in mind that a contract may have to be signed… to know more about Gaia-X’s thoughts about that, look at one of our articles).
Gaia-X Credential Event Service
As mentioned above, all the Gaia-X conformant catalogues must be synchronised to avoid a gravity effect (if one catalogue gets more events than the others, it should thus attract everything) and break the trust chain. To do so, the Gaia-X Credential Event service is used. But how does it work?
Each participant is calling a Gaia-X Digital Clearing House Compliance Engine. As a result, a Verifiable Credential is generated and given to the requester (aka the participant). Then, each participant is, voluntarily, pushing these credentials towards the Credential Event Service.
To be noted that only the resolvable ID of the verifiable credentials are pushed in CES, not the credential content itself. Then, each CES consumer must resolve the ID and request access to the holder of the verifiable credentials. This mechanism ensures that the holder is at any time in control of who can access its data.
Using the Credential Event Service API, each catalogue can have access to the Verifiable Credentials shared since the last call and decide whether to retrieve them or not (depending on its own rules).
Note that all kinds of Verifiable Credentials returned by Gaia-X Compliance Service (resolving the credential subject ID will build a link towards the original Verifiable Credentials) are forwarded through the Credential Event Service.
But now, it is time to open your gifts 🎁, and discover how the Credential Event Service (CES) is technically working.
There are two ways to interact with the Credential Event Service: you can either share credentials to make them available for catalogues, or you can consume the stream of incoming credentials.
Share credentials
Pushing a new credential to the CES is quite simple. Take the output from the compliance service and post it to the CES publication endpoint. It we be made available to all catalogues.
Your credentials must be sent as a Cloud Event (you can see the specifications here: https://github.com/cloudevents/spec).
Below is an example of credential emission written in Python.
Not familiar with code? No problem! The Gaia-X lab Wizard can push the credentials to the CES for you. We will test it out on a development instance.
- Go to https://wizard.lab.gaia-x.eu/development
- You can either create your credentials using the “Participant VCs in 4 steps” or import your existing signed documents.
- Call the compliance, select the credentials, and submit them. You get a Compliance Verifiable Credential as a result.
- Submit it to the CES using the “Share” button.
And that is it, the credentials are now shared with connected catalogues through the CES.
Consume credentials
Catalogues need to pull, on a regular basis, the new events from the CES offering endpoint. It is a paginated request, and you can use the lastReceivedId query parameter to list the credentials received after a given event ID.
Translated to Python code it gives:
You can set up a task to execute periodically the new events search and persist them into your catalogue.
You can get the full description of the API on Swagger: https://ces-v1.lab.gaia-x.eu/q/swagger-ui/.
The Gaia-X lab provides an open-source catalogue example: https://catalogue.lab.gaia-x.eu/development.
It lists credentials pushed to the development instance of the CES. Note that the credentials must be resolvable, otherwise this catalogue will ignore them.
Conclusion
Building trust in the Data Economy is not only a matter of certification of Participants (providers and consumers). Tools, interacting with participants, also must understand, use, and propagate this chain of trust, which means in Gaia-X Ecosystem to use Catalogues able to deal with Gaia-X Verifiable Credentials.
If you want to know more about how consumers can select their data providers based on an evaluation of their trust level, stay tuned!
