Skip to main content

Credential Data Schema

Introduction

Unum ID enables securely sharing verified

A credential is a collection of data about a person. It's issued by a company (i.e. created and sent to a user) and stored in the company's app, on that user's device.
Example: ACME Bank issues a KYC verification credential to Richard (an ACME user). This includes Richard's contact information and account numbers, as well as a level of confidence in the accuracy of the data.
Components: A company issues credentials using the Server SDK, and an app stores credentials using the Mobile SDK.
credential data amongst network participants. While in theory this data can take any shape, a structured schema must be defined and followed for every credential type for the sake of all network participants.

We opted to format our data using W3C's Linked Data serialized via JSON-LD. It gives us the structure to create a data validation framework along with a human readable vocabulary around the data. We feel this meets our goal to have a credential schema definition that is robust enough to encapsulate and define any data with the property of being easily displayed and validated.

note

JSON-LD is serialization the syntax used in the W3C's Verifiable Credential and Decentralized Identifier recommendations of which our data network is built around.

Our entire human readable JSON-LD context semantics file can be download and viewed via, https://schema.unumid.co/context. The context file serves as a building block for the basis for the shared vocabulary that ultimately make up our credential data schemas. However more than likely as an

An issuer is a role a company can play to issue credentials to subjects (users). An issuer also change credential statuses, for example to revoke credentials.
Example: ACME Bank issues a KYC verification credential to Richard (an ACME user). It later revokes that credential and issues a new one to Richard to update his information.
Components: An issuer issues credentials and changes credential statuses using the Server SDK.
issuer or
A verifier is a role a company can play to verify presentations shared by subjects (users). A verifier can also make requests for presentations and send them to subjects.
Example: Hooli FinTech sends Richard a request for (a presentation of) a KYC verification credential from ACME Bank. When Richard shares the presentation, Hooli verifies it.
Components: A verifier requests and verifies presentations using the Server SDK.
verifier you want to know what is the schema for a particular credential type.

To view all of the Unum ID defined credential schemas one can do so via, https://schema.unumid.co/schema. If you want to know the schema for a particular credential type one can use that same url with the desired credential type as a query param, for example https://schema.unumid.co/schema?type=EmailCredential.

tip

We have this API documented via our public Postman collection documentation under Schema Resolver.

You can view the response bodies from https://schema.unumid.co/schema in the browser but probably best to format the json response for human readability.

info

Given use of JSON-LD standard for schema definitions we hope it make Issuer defined credentials schemas a reality very soon. However, until then, all credential types have schemas defined by Unum ID. Please let us know if you would like to define a new credential schema for your use case.

We currently are opting to only support what can be referred to as "single attribute atomic credentials". This means that we break data into into it simplest form for every credential. This is to provide users a means of selective disclosure for

A request (or presentation request) is a request for a presentation. It's sent by a company to a user, who chooses whether to share a presentation in response.
Example: Hooli FinTech sends Richard a request for (a presentation of) a KYC verification credential from ACME Bank.
Components: A company creates requests using the Server SDK and routes them to users using the Web SDK. A user's app responds to requests using the Mobile SDK.
requests with optional fields.

Example

Below is code level example of how to comply with the schema definitions when issuing credentials. In this example we are following the AddressCredential and FullNameCredential schemas.

/*The credential data compliant with the Address and FullName Credentials schemas*/
const credentialDataList = [
{
type: 'AddressCredential',
address: user.address
},
{
type: 'FullNameCredential',
fullName: user.fullName
}
];

const unumDtoCredentialResponse: UnumDto<Credential[]> = await issueCredentials(
issuerEntity.authToken,
issuerEntity.did,
userDid,
credentialDataList,
issuerEntity.signingPrivateKey