Skip to main content

Proof Schemas

A proof schema defines the attributes you want to request from a credential holder. You create a proof schema once and reuse it each time you make a proof request of that type.

Proof schemas are built from claims defined in credential schemas. Each requested attribute must exist in a credential schema in your organization. A single proof schema can draw attributes from any number of credential schemas, regardless of credential format.

Prerequisites​

Create a proof schema​

Call POST /api/proof-schema/v1 (Core | Desk) to create a proof schema.

A proof schema requires a name and at least one entry in proofInputSchemas. Each entry in proofInputSchemas references a credential schema and specifies which of its claims to request:

{
  "name": "Employment Verification",
  "proofInputSchemas": [
    {
      "credentialSchemaId": "38e563ac-e7b5-4861-bdd4-00789692f159",
      "claimSchemas": [
        {
          "id": "e810f49e-3cb2-4ffe-97b8-4dbd90bc37cd",
          "required": true
        },
        {
          "id": "1be6cd3e-118c-46dc-a2c7-403c83994a48",
          "required": false
        }
      ]
    }
  ]
}

The id of each entry in claimSchemas is the UUID of the claim as defined in the credential schema. Retrieve a credential schema to find the claim UUIDs:

curl -L '/api/credential-schema/v1/{{CREDENTIAL-SCHEMA-UUID}}' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'

The required flag controls whether the holder must present that specific claim to satisfy the proof request.

Request attributes from multiple credential schemas​

To request attributes from more than one credential schema, add an entry to proofInputSchemas for each:

{
  "name": "Job Application",
  "proofInputSchemas": [
    {
      "credentialSchemaId": "9a3d0f5c-0faf-4ca0-8401-3c625c0582b3",
      "claimSchemas": [
        {
          "id": "eaca8d22-decb-47a0-85ab-69aa3fc064e4",
          "required": true
        },
        {
          "id": "6e269a09-da9b-461a-8e32-1ce1573f9647",
          "required": true
        }
      ]
    },
    {
      "credentialSchemaId": "a3c357f5-502f-4ede-8a52-77beb6fdc4cb",
      "claimSchemas": [
        {
          "id": "a4c33923-0d28-4046-97c3-4edb16bf5f29",
          "required": true
        }
      ]
    }
  ]
}

Data retention​

By default, claim data shared by a holder in response to a proof request is retained indefinitely. Use the expireDuration parameter to set a retention period in seconds:

{
  "name": "Employment Verification",
  "expireDuration": 2592000,
  "proofInputSchemas": [...]
}

When shared data reaches its expireDuration, and when the corresponding task is run, the system permanently deletes all claim values from the proof request.

See Managing Claim Data for details.

Import proof schemas​

Proof schemas can be imported by mobile verifiers, making it easy to distribute them across an organization.

Call the Share proof schema endpoint (Core or Desk) to generate a URL. The mobile verifier then calls Import proof schema (Core) to import it and begin making proof requests.

Mobile verifiers can also assemble proof schemas directly after importing the necessary credential schemas. See Importing credential schemas.