# A new community

Let’s imagine a community of organisations that want to exchange verifiable credentials (VC): the NGO federation in Uqbar _(a fantastic country from J. L. Borges literature)_. There will be five roles:

1. *Trusted authority organisations (TAO)*: the governmental entities with authority to recognise legal actors in Uqbar.
2. *Trusted Issuers (TI)*: NGOs that relate to people as employees, members or beneficiaries. They can receive credentials from any of these NGO as a credentialSubject.
3. *Holders*: citizens or organisations that can hold credentials. They hold them in their private wallet.
4. *Verifiers*: organisations that can accept the presentation of credentials from subjects wich are interested in any benefit from verifiers (e.g. access or discount). The information in these credentials about these holders/credentialSubjects come from issuers, which may be accredited or recognised as such by trusted authority (Uqbar government).
5. *Public registries*: where identifiers (DID), schemas, accreditations, VC issuance are registered. This registry is a trusted third-party, reachable to all, stores minimal data, and replicated to avoid data or service loss or tampering.

This is the scenario according to EBSI, derived from the W3C model for VC:
![EBSI schema](img/ebsi-model.png){ align=center }



Ideally, the *Friends of Uqbar* (FoU) organisation receives a NGO paper accreditation and a VC (c1) after registration from Uqbar's tax authority, and a NGO federation (NGOF) member VC (c2). These two credentials are deposited in a public digital registry. These VC allow FoU to operate as NGO in Uqbar.

The *NGO federation* can agree with Uqbar's *education ministry* on an accreditation for certain degrees and the fields to include in a training VC for all their member organisations. These diplomas comply with the schema of any training diploma in Uqbar (include data fields, required or optional, defined the education ministry) and those defined by NGOF for their courses. The NGO federation receives an accreditation from the Ministry of Education, and issues another accreditation to all member NGOs that pass a training course and qualify as training actors and therefore diploma issuers to trainees.

Vulnerable Smith is a beneficiary person of FoU. FoU knows well his situation and receives in his ID wallet a VC (c10) as beneficiary signed by FoU. In that VC it details he passed a training course and is qualified to work as a blacksmith operator. The issuance of that VC (minimal details, at least its unique ID) is registered in a public registry.

V. Smith applies for a job in the *Iron for good* (IfG) NGO. He has to fill in a web form for that but furthermore he can present IfG the VC with his professional qualification. 

In summary, we have these organisations:

- TAO: tax authority, education ministry, NGO federation

- Trusted issuer: FoU

- Credential subject: V. Smith citizen

- Verifier: IfG

The list of credentials (VC accreditations):

- c1: As a registered org, issued by Tax authority to FoU.

- c2: As a registered NGO, issued by NGOF to FoU.

- c10: As a beneficiary subject, issued by FoU to V. Smith

The web form details may not be trusted but the presented VC (c10) by V. Smith to IfG is verifiable:

- The presentation act (of c10) by V. Smith (from his wallet) is signed by the applicant (V. Smith). 

- The details included (in c10) are about V. Smith himself as credentialSubject, are signed by the issuer (FoU). 

- The issuer, FoU, has other credentials issued by Uqbar's tax office (c1) and NGOF (in c2) with FoU as credentialSubject, that confirm that FoU is a valid/accredited issuer for a beneficiary VC.

- These credentials (c1, c2, c10) are registered in the public registry. 

- All actors who trust Uqbar's government will also trust all these credentials (chain of trust).

- VC issuers can always revoke credentials if they change their mind (e.g. V. Smith is proven to cheat in the revision of the final exam) by adding his training credential (c10) to the VC revocation list in the public registry. The same can apply for FoU for any wrongdoing by FoU, with their VC (c2) revocation. 

- VC do not ring home. Since all verifications rely on actor and credential identifiers that are stored in the public registry, FoU never knows, is never contacted, by employers so does not need to know if V. Smith used the credential or not and which employers he contacted.

- The standardisation of the fields, their meaning, types and correct values, required and optional ensures any of the associated VC can be used, are well understood and recognised by any actor in Uqbar.

- Any actor in Uqbar has a unique identifier (the decentralized identifier or DID) and two keys associated. The public key, that can be deducted (looked up) from the actor's DID, and the private, that as the name says is never shared by an actor. A signature string generated by the private key can be verified by anyone using that actor's public key. Therefore my address is my DID, that leads to find my public key. My identity consists on holding my private key. Sharing my identity is too risky as I am sharing my identity too: another actor can act as me (my DID) publicly.

## A community agrees and publishes about their credentials

For NGO community members, to issue training credentials for vulnerable citizens, they have first to publish a set of documents with several agreed upon details about their training credentials for public awareness:

## Context: 
(check [./context](https://github.com/eReuse/IdHub/tree/release/context) folder)
The terms used to refer to credential fiels: the context (vocabulary or terms for fields) for credentials issued by that community: which terms are agreed upon and which definitions to avoid misunderstandings:
For instance: [course credential](https://github.com/eReuse/IdHub/blob/release/context/course-credential.jsonld).

Let’s take "firstName": "https://idhub.pangea.org/tree/release/context/#firstName”
“firstName” is the term of that vocabulary and "https://idhub.pangea.org/context/#firstName” is the unique identifier given to that definition. It looks like a URL but doesn’t need to work as such. 

It allows for the detection of different interpretations when these identifiers differ. For instance, “firstName” with ID “https://libraries.org/context/#firstName” may not accept the same values as the previous, even if the term is the same since namespaces are different and each community can have their specific definitions and expectations.
Not in this case, but if these identifiers work as Web URLs, a visit to that URL on a web browser could bring a web page that describes that term for humans in more detail: precise definition, meanings, possible values, etc.

## Schemas: 
(check [./schemas](https://github.com/eReuse/IdHub/tree/release/schemas) folder)
The credential schema for that credential defines the correct structure, fields, and values, with mandatory and optional fields and possible values, including type and syntax. It allows checking whether a given credential instance is valid or not broken before being processed.
For instance: [course credential](https://github.com/eReuse/IdHub/blob/release/schemas/course-credential.json).

## Templates: 
(check [./idhub/templates/credentials](https://github.com/eReuse/IdHub/tree/release/idhub/templates/credentials) folder)
The credential template for that credential is a generic credential with placeholders for each possible value.
For instance: [course credential](https://github.com/eReuse/IdHub/blob/release/idhub/templates/credentials/course-credential.json).


## Spreadsheet: 
(check [./examples/excel_examples](https://github.com/eReuse/IdHub/tree/release/examples/excel_examples) folder)
Once the credential template is ready, there is need (IdHub developers have a Python script to generate that automatically, will soon be published) that generates a spreadsheet template from most fields in the credential template: an empty XLSX spreadsheet that includes as many columns as credential fields, both mandatory and optional, the comments in each column for each field, the corresponding cell format for the column cells according to what is specified to facilitate data import.
For instance: [course credential](https://github.com/eReuse/IdHub/blob/release/examples/excel_examples/course-credential.xlsx).


# In summary

As you can see, communities should agree and publish details about the credentials they are going to use and exchange. NGO members can issue these credentials, and third parties, verifier organisation, can accept these since they can understand the content, given all details about them are public and clear. Others can verify the credential integrity from the signature by an NGO member given its DID, and that the issuer DID corresponds to an accredited member of the NGO federation, and even registered in Uqbar's government. These accreditations are also VC issued by TAO to TI organisations. 

For that reason, we don’t have a UI in IdHub to add support for new credential types, but once there is a public community agreement on context, schema and templates, these files can be included in the IdHub's corresponding folders, and even an model (with no subject's data) spreadsheet can be generated with a clear structure to fill in and issue on IdHub any number of these credentials at once.

IdHub relies on sending email invites for credential issuance, therefore an email address is a key initial requirement for any actor to use IdHub, among others required during installation. Then, IdHub generates a DID, public key, private key, and can issue VCs to that actor. 

One current limitation of IdHub is that each issuer organisation creates a wallet to their VC holders. Therefore, a person related to multiple issuer organisations has as many separate web wallets. We plan to address that limitation soon with you contributions to further development to allow for a single wallet per person. Thanks in advance!

