Proof schemas

Proof schema operations

Core API & Desk API

A proof schema defines the attributes a verifier requests from a credentials holder. It is the collection of items of information to be requested.

For example, an employer wanting to fill a vacant position could create a proof schema to accept certificates of employment and university diplomas. Then, with each new application, the hiring employer makes a proof request using this proof schema each time. The applicants then would share their relevant credentials as part of the job application.

Proof schemas are built from attributes defined in credential schemas. Each item of information to be requested must first be part of a credential schema in the system. Proof schemas are not restricted to pulling attributes from a single credential schema or from credential schemas using a particular credential format; a single proof schema can be composed of any number of attributes from any number of credential schemas within the organization. Restrictions for proof schema creation are noted below.

See the credential schemas guide for information on building credential schemas.

Proof schema restrictions

A holder's presentation must be signed by the same key that signed the credential being shared. This means the holder cannot submit two credentials signed with different keys in the same presentation; holder presentations of more than one credential only work if the holder's key is the same in all credentials.

As a result, when creating proof schemas it is not possible to combine hardware- and software-based credentials. For proof requests with multiple credentials, all credentials must have the same walletStorageType. See the wallet storage type guide.

Importing proof schemas

Proof schemas can be imported to mobile verifiers, making it easy to disseminate them within organizations.

Call the Share proof schema endpoint (for Core or Desk) to generate a URL. Then the mobile verifier can call the Import proof schema (for Core) to import the proof schema and begin requesting proofs.

Proof schemas can also be assembled directly by mobile verifiers, after importing the necessary credential schemas. See the importing credential schemas guide.

claimSchemas object

The claimSchemas object is the array of items of information to be requested in a credentials verification. Each attribute to be requested is identified by the id of the attribute originating from a claims object. Pass an array of the ids of whichever attributes will be requested.

Data retention

By default the data a digital wallet holder shares when completing a proof request is retained in the system indefinitely. This can be changed at the proof schema-level.

When creating a proof schema using /api/proof-schema/v1, use the expireDuration parameter to specify the length, in seconds, that data shared in response to proof requests made using this schema should be retained in the system.

For those proofs which will be deleted, the retainUntilDate field when retrieving proof requests provides the deletion time.

Additionally, claim data from proofs can be manually deleted via the /api/proof-request/v1/{id}/claims endpoint.

Deletion

When shared data reaches its expireDuration, the system:

• Updates the proof request
  • Deletes all values from any claims
  • Deletes the credential object from proofInputs
  • Adds claimsRemovedAt to the proof request
• Creates a history entry
  • entityType = PROOF
  • action = CLAIMS_REMOVED

The proof itself remains, including metadata, but the claims which were shared by the digital wallet holder are permanently deleted.