# IdHub for 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 three roles:
* Trusted authority organisations (TAO): the governmental entities with authority to recognise legal actors in Uqbar.
* 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.
* Holders: citizens or organisations that can hold credentials. They hold them in their private wallet.
* 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).

Ideally, Friends of Uqbar (FoU) organisation receives a NGO paper credential and a VC (c1) after registration in Uqbar's government, and a NGO federation member VC (c2). These two credentials are deposited in a public digital registry. These VC allow PAN to operate as NGO in Uqbar.

Vulnerable Smith is a beneficiary of FoU. PAN know well his situation and it receives in his ID wallet a VC (c10) as beneficiary that describes he passed a training course and is qualified to work as a entry-level blacksmith. The issuance of that VC (minimal details, at least its unique ID) is registered in a public registry (replicated to avoid data or service loss or tampering).

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. The web form details may not be trusted but the presented presented VC (c10) is verifiable: The presentation act (of c10) is signed by the applicant (V. Smith). The details included (in c10), about V. Smith as credentialSubject, are signed by the issuer (FoU). The issuer, about FoU as credentialSubject is recognised (in c1) by Uqbar's government and the NGO Federation (in c2). These credentials (c1, c2, c3) are registered in the public registry. All actors trust these credentials, and issuers can revoke credentials if they change their mind (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. In addition, since all verification rely on actor and credential identifiers stored in the public registry, FoU never knows is never contacted by employers so does not know if V. Smith used the credential and which employers he contacted.

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 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 the NGO federation for their courses.

That standardisation of the fields, their meaning, types and correct values, required and optional ensures any of the associated VC 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.

## The community publishes public details about their credentials for public usage
For the NGO community to use IdHub to issue training credentials for vulnerable citizens they have first to publish a several agreed details about their training credentials:

## Context: 
(check [./context](https://github.com/eReuse/IdHub/blob/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/context/#firstName”
“firstName” is the term of that vocabulary
"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/blob/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.

## Templates: 
(check [./vc_templates](https://github.com/eReuse/IdHub/blob/release/templates) folder)
The credential template for that credential is a generic credential with placeholders for each possible value.

## Spreadsheet: 
(check [./vc_excel](https://github.com/eReuse/IdHub/blob/release/vc_excel) 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 XLX 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.

As you can see, communities should agree and publish details about the credentials they are going to use. 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, and 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 IdHub corresponding folders, and even we can generate an empty spreadsheet 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. 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 organisation has multiple separate 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!

