Skip to main content

Data Schemas

Introduction​

Verified Inc. enables securely sharing verified

A credential is a collection of data about a person. It's issued by a company and can be requested by other network participants, gated by the user's consent.
Example: ACME Lending 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 following the steps in the Issuance Guide.
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 use JSON Schema syntax for data validation purposes via a pre-compiled AJV engine. This ensures our credential schemas are robust enough to encapsulate any data while still being easily described, displayed, and validated.

Schema Definitions​

You can view all of the Verified Inc. defined credential schemas via https://schema.verified.inc/schema. If you want to know the schema for a particular credential type you can use that same url with the desired credential type in the path. For example, https://schema.verified.inc/schema/EmailCredential, would yield the EmailCredential's schema information.

tip

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

It is possible to view the response bodies from https://schema.verified.inc/schema in the browser, but we recommend Postman, which automatically formats the JSON response for human readability.

important

We hope to soon make it possible for you as a

A customer is a company entity that serves as a parent to brands and their corresponding ApiKeys.
Example: ACME Bank is the Verified Inc. customer where their self service dashboard access rights are defined.
Components: The admins of the customer can manage individual brand settings.
customer to define your own credential schemas. But currently, we Verified Inc. define all credential schemas. If you would like a new credential schema for your use case, please let us know and we will gladly define one for you.

We currently support what can be referred to as "single attribute atomic credentials" and "composite credentials".

Atomic credentials provide users a means of selective disclosure for

A request (or credential request) is a request for a credentials to be shared by a user. It's created when a company successfully checks if a user has matching credentials, via /hasMatchingCredentials. Only if the user has the ability to response with the matching credentials is a request created.
Example: Hooli FinTech checks if Richard has a SSN and LastName credential issued by ACME Lending. Because he does, a request is created for those credentials specifically from ACME Lending. Hooli presents this request to Richard by directing him to the `url` received in the `/hasMatchingCredentials` response body.
Components: A company creates a user specific request by using /hasMatchingCredentials.. If it is case the user does not have the desired credentials then a request is not created. If it is the case the user does, a request is created and is returned in the form of a `url` attribute in response to the client.
requests with optional fields.

Composite credentials are credentials that contain multiple "Atomic Credentials". For example, the FullNameCredential contains FirstNameCredential, LastNameCredential and MiddleNameCredential. This provides a means of grouping atomic credentials with related data.

JSON Schema​

The /jsonSchema path will return the JSON schema definition, e.g. https://schema.verified.inc/jsonSchema/FirstNameCredential:

Example FirstNameCredential JSON Schema
{
  "$id": "FirstNameCredential",
  "type": "object",
  "properties": {
    "firstName": {
      "description": "A person's first name",
      "examples": ["John", "Mary Kate"],
      "title": "First Name",
      "displayFormat": "String",
      "type": "string"
    }
  },
  "required": ["firstName"]
}

For composite credential schemas, the object will contain a allOf property, which is an array of the atomic credential schemas:

Example FullNameCredential JSON Schema
{
  "$id": "FullNameCredential",
  "type": "object",
  "allOf": [
    {
      "$ref": "FirstNameCredential"
    },
    {
      "$ref": "LastNameCredential"
    },
    {
      "$ref": "MiddleNameCredential"
    }
  ]
}
tip

Note that each attribute has a description and examples to help you understand the credential's schema. If you need more detailed information, look at our open source schema-sdk formats.

tip

The $ref property is a JSON Pointer, which is a string containing a URI fragment identifier. In this case, it is a reference to another schema. This is how we define composite credential schemas.

note

It's important to note that each of these credentials inside FullNameCredential are single attribute atomic credentials, so you are able to request individually. But if you need create or request a CityCredential and a StateCredential you will need to use AddressCredential so data doesn't get mismatched.

Schema Library​

Search for or select a schema, see its properties and attributes, and copy the schema JSON:

Example​

First, we get the JSON schemas for the SsnCredential, FullNameCredential, which contains FirstNameCredential and LastNameCredential and review their attributes' descriptions and examples.

Next, we construct valid credential bodies, according to the schemas:

/*The credential data compliant with the Ssn, FullName (FirstName and LastName) Credentials schemas*/
const credentialsList: Credentials = [
  {
    type: 'SsnCredential',
    data: {
      ssn: '333224444',
    },
  },
  {
    type: 'FullNameCredential',
    data: [
      {
        type: 'FirstNameCredential',
        data: {
          firstName: 'John',
        },
      },
      {
        type: 'LastNameCredential',
        data: {
          lastName: 'Doe',
        },
      },
    ],
  },
];
Example Request Body for Issuing Credentials
{
  "credentials": credentialsList, // a list of one or more Credentials objects
  "email": "richard.hendricks@pipedpiper.net"
}