Hyperledger Aries ACA-Py Agents Setup and Running Tutorials — Part V — Credential Schema and Definition Creation
Introduction
In Part I, I’ve introduced the general benefits of using SSI and why Hyperledger Indy and Aries can fit in the big picture. In Part II, a scenario overview and tools were described. Part III shows details on how to set up a Dev environment to run an ACA-Py agent V0.6.0. In Part IV, it focused on the one-time agent level connection channel establishment. This Part V will describe how to create a credential schema as well as its relevant credential definition.
Before showing the hands-on part, I’ll give a brief clarification on the concept of a credential, a credential schema and a credential definition to help you refresh your mind if you might not know them very well.
What Is A Credential?
In the world of IT, different people might understand credentials differently. Confusions arise on this notion for IT guys have different conversations, so there is no surprise this could even confuse normal system users. The notion of a credential in today’s world is more related to an authentication/authorisation token (e.g. OAuth tokens, SAML tokens, X.509 certs) that are normally used for users to authenticate themselves for logging into systems with the proper access control.
However, in the world of SSI (stands for Self Sovereign Identity), this credential concept came from paper-based credentials such as passports, driving licenses or uni degrees. The common features of those paper-based credentials are these credentials are issued by proper authorities/issuers. Whilst the authenticity of these paper-based credentials can be verified by those authorities/issuers, those paper-based credentials are actually held by each individual human being, who has the full control on deciding whether s/he would like to show one or more his/her own paper-based credentials to others or not. In addition, the use of these paper-based credentials is not limited for authentication/authorisation purposes, but can also be used for other purposes (e.g. screening).
SSI adopted this notion of paper-based credentials and mapped them to the digital world and referred them to as digital credentials. Therefore, in the world of Hyperledger Indy/Aries, credentials means digital credentials that could be used as either digital twins to existing paper-based credentials or without even having its real physical counterparts.
What Is A Credential Schema?
One could probably infer from the “schema” word here to have a quick guess on what it is. It specifies the structure of a credential. If we take a general passport credential as an example, a passport normally has some attributes along with values as key/value pairs as shown below:
FirstName: Peter
LastName: Pan
Age: 14
…
The credential schema defined here includes: FirstName, LastName, Age as well as other attributes that are omitted in the above example.
In the world of Hyperledger Indy, only an issuer can define the credential schema, and this credential schema will eventually be stored on the Indy DLT ledger — Layer 1 of ToIP as shown in Part I.
In reality, a new credential type might be initially defined by the first party who would run as an authority if it was the only one that initialised this new credential type, and later on, the widespread of how a new credential would look like (e.g. what attributes) might require other parties to collaborate with this first party to form an ecosystem to eventually agree on how it should be defined properly (e.g. like how W3C defines many web standards such as DID).
A credential schema defines a general structure of how a credential should look like. As mentioned above, we should expect the evolution of a credential to happen that means new attributes could be added or old attributes could be discarded. Therefore, Indy does support the credential schema versioning.
Pragmatically, the ACA-Py agent that runs as the issuer is going to define the credential schema. One question came to my mind even before I started my hands-on experiences on ACA-Py was whether there were any predefined/built-in attributes common to all credentials (e.g. issued date, expired date) in ACA-Py, and the answer is No. This means it is completely the issuer’s responsibility to define all needed attributes that will be used for a credential in its schema design.
What Is A Credential Definition?
In the world of Indy, the issuance of a new credential is not based on the credential schema but on its relevant credential definition. A credential schema sets up a foundation layer for how a credential should look like and how many versions are available, and a credential definition is defined on top of a particular credential schema and used by an issuer. Therefore, when multiple issuers join the same ecosystem, they can define their own credential definitions on whichever credential schema version(s) of the same credential type.
Again, pragmatically, the ACA-Py agent that runs as the issuer is going to define the credential definition, and this credential schema will eventually be stored on the Indy DLT ledger
Personally, I don’t see a clear value of adding the credential definition concept in Indy. If we removed this concept, the relationship between a credential schema and issued credentials would be one-to-many, which was flexible enough. Adding this credential definition in between the credential schemas and issued credentials adds one more one-to-many layer, which eventually adds more complexity to the use cases.
Let’s use figure 1 as an example to see how we want to define a new passport credential in Indy and Aries. The first row shows the highest roadmap on how we want to do it. We design the passport credential as a new credential type from our mind and write them down on a piece of paper at a conceptual level; then define it in a Credential Schema starts with Version 1(CSV1) in Aries and Indy; then create its Credential Definition 1 (CD1) based on CSV1; then issue credentials 1 to n based on CD1. The same process will repeat again, if CSV1 is updated to a Version 2. Anyway, even I put my argument on the real value of this credential definition used in Indy/Aries here, may be I’m not aware of its true value hiding some where, this is a mandatory in ACA-Py before issuing a credential.
Hands-on Process
Hope the above clarifications on the credential schema and definitions make sense. Eventually, I’m going to show you how easily we can use ACA-Py V0.6.0 to enable an issuer to create a new credential schema and definition. Note: please make sure you’ve followed all my previous blogs and set up an issuer agent, the holder agent is not needed here. Also, when I write each Part of the blog, I have to rerun the whole process from the beginning. So if you see information (e.g. issuer and holder’s connection IDs) in the figures in each Part is different from a previous Part, this is normal, as these IDs are newly generated for each process.
You can now call a POST API named: /schemas on the issuer agent. In the JSON body, put below key/value info (see figures 2 and 3).
“attributes”: an array of attributes used in a credential
“schema_name”: the name of this credential schema
“schema_version”: version of the credential schema
You can now call a POST API named: /credential-definitions on the issuer agent. In the JSON body, put below key/value info (see figures 4 and 5). This call could take a few seconds.
revocation_registry_size: size of the revocation registry, for dev purpose, just put 1000.
schema_id: the value as generated in the schema API call response
support_revocation: true or false. This indicates if this credential definition can be relocated. If true, it will automatically create a revocation registry.
tag: put any meaningful messages.
You can now call a GET API named: /revocation/registries/created on the issuer agent, you can see two revocation registries have been created.
Copy one of the ids and call a GET API named: /revocation/registries/{rev_reg_ids} on the issuer agent, you can find the newly created credential definition (see line 9 in figure 7).
That’s it. It’s very straightforward to make the credential schema and credential definition creation work in ACA-Py.
Conclusion
This Part tries to clarify why Indy and Aries need to use credential schema and definition. Part VI will focus on the process of credential request, issuance and reception between two agents. See you there.
