Skip to main content

Credential Schemas

Our credential schemas ensure user data is predictably structured. We use JSON Schema syntax for data validation purposes via a pre-compiled AJV engine. This makes our schemas robust enough to encapsulate any data while still being easily described, displayed, and validated.

All Verified credential schemas are accessible at https://schema.verified.inc/schema. To get the schema for a particular credential type, use the same URL with the credential type in the path. For example, https://schema.verified.inc/schema/AddressCredential yields the schema for an AddressCredential.

tip

These schemas are documented in our public Postman collection under Schema Resolver. We recommend using Postman for this because it formats the schema JSON for easier readability.

Let Us Know If You Need New Schemas

If our current credential schemas don't accommodate your use case, please reach out to us at Support@Verified.inc and we'll be happy to create new schemas for you.

Schema Definitions​

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"
}