#Data Functions

The walt.id issuer API offers the use of data functions when issuing VCs. These functions ensure that the credentials issued always contain the most current and accurate information.

#How Data Functions Work

Data functions are not executed at the moment you create an OpenID credential offer URL via the walt.id issuer api. Instead, they get executed at the point when the credential is actually claimed by the recipient. This means that the data within the VC stays up-to-date, regardless of whether the recipient claims it immediately or after a considerable period.

#The Importance Of Timing

This delayed execution is crucial because it guarantees the information's relevance and accuracy. For example, a credential might be issued today but claimed a month later. The data functions ensure that the VC reflects any changes that occurred during that interval, maintaining the credibility of the credential.

#How To Use Data Functions

When issuing a credential you have the option to provide a JSON Object called mapping that defines which keys in the credential data structure should be replaced by the value returned of the provided data function. Data functions can return any type of value from a String, Number of whole JSON Object. Therefore, as seen in the example below the degree which is a nested object can be generated on the fly via the JSON webhook.

#Example

Credential To Issue

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "",
  "type": [
    "VerifiableCredential",
    "UniversityDegreeCredential"
  ],
  "issuer": {
    "id": ""
  },
  "credentialSubject": {
    "degree": ""
  }
}

Mapping Object With Data Functions

{
  "id": "<uuid>",
  "issuer": {
    "id": "<issuerDid>"
  },
  "degree": "<webhook-json:https://example.com/api/degreeJSONData>"
}

Example Issuance API Call Body

{
  ...
  "credentialData": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "id": "",
    "type": [
      "VerifiableCredential",
      "UniversityDegreeCredential"
    ],
    "issuer": {
      "id": ""
    },
    "credentialSubject": {
      "degree": ""
    }
  },
  "mapping": {
    "id": "<uuid>",
    "issuer": {
      "id": "<issuerDid>"
    },
    "degree": "<webhook-json:https://example.com/api/degreeJSONData>"
  }
  ...
}

Issued credential

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.gov/credentials/3732",
  // return value from data function
  "type": [
    "VerifiableCredential",
    "UniversityDegreeCredential"
  ],
  "issuer": {
    "id": "did:web:vc.transmute.world"
    // return value from data function
  },
  "credentialSubject": {
    "degree": {
      // return value from data function
      "type": "BachelorDegree",
      "name": "Bachelor of Science and Arts"
    }
  }
}

#Available Functions

These functions can be used within the mapping object of the issuance request. For details on issuance, you can read this guide A list of functions with their correct syntax to be used in the mapping object below:

#UUID

<uuid> to get a unique identifier.

#Subject Did

<subjectDid> to get the recipient's DID once the credential gets claimed.

#Issuer DID

<issuerDid> to get the subject did.

#Timestamp

<timestamp> to get the current timestamp in ISO 8601 format YYYY-MM-DDThh:mm:ss.sssZ

#Timestamp Seconds

<timestamp-seconds> to get the Unix timestamp.

#Timestamp In

<timestamp-in:duration> to get a future date by providing the duration as an argument (e.g., "timestamp-in:365d" for one year from now). Returned timestamp will be in ISO 8601 format YYYY-MM-DDThh:mm:ss.sssZ

#Timestamp In Seconds

<timestamp-in-seconds:duration> to get a future date by providing the duration as an argument (e.g., "timestamp-in-seconds:365d" for one year from now). Returned will be a Unix timestamp.

#Timestamp Before

<timestamp-before:duration> to get a date in the past by providing the duration as an argument (e.g., "timestamp-before:365d" for one year ago from now). The returned timestamp will be in ISO 8601 format YYYY-MM-DDThh:mm:ss.sssZ

#Timestamp Before Seconds

<timestamp-before-seconds:duration> to get a date in the past by providing the duration as an argument (e.g., "timestamp-before-seconds:365d" for one year ago from now). The returned value will be a Unix timestamp.

#Webhook

<webhook:url> to make a request to a specific URL. It will insert the response of the request as a plain text string. The webhook URL is provided as an argument (e.g., "webhook:https://example.com").

For example if we have the following mapping during credential issuance:

{
  "vc": {
    ...
    "credentialSubject": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "degree": {
        "type": "BachelorDegree",
        "name": "Bachelor of Science and Arts"
      }
    }
  },
  "mapping": {
    ...
    "credentialSubject": {
      "id": "<subjectDid>",
      "degree": {
        "name": "<webhook:https://example.com>"
      }
    },
    ...
  }
}

And the webhook endpoint responds with a content-type of text/plain with "Test Data". The issued credential will look like:

{
  ...
  "credentialSubject": {
    "id": "did:key:z6MkuHcPf3jhFwGso9agCvbvpzsbn6gHtYYNudXxHjQW1zQd#z6MkuHcPf3jhFwGso9agCvbvpzsbn6gHtYYNudXxHjQW1zQd",
    "degree": {
      "type": "BachelorDegree",
      "name": "Test Data"
    }
  },
  ...
}

#Webhook JSON

<webhook-json:url> to make a request to a specific URL. It will insert the response body as a nested JSON object. The webhook URL is provided as an argument (e.g., "webhook-json:https://example.com").

For example if we have the following mapping during credential issuance:

{
  "vc": {
    ...
    "credentialSubject": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "degree": {
        "type": "BachelorDegree",
        "name": "Bachelor of Science and Arts"
      }
    }
  },
  "mapping": {
    ...
    "credentialSubject": {
      "id": "<subjectDid>",
      "degree": "<webhook-json:https://example.com/api/dataJson>"
    },
    ...
  }
}

And the webhook endpoint responds with a content-type of application/json and the following data:

{
  "type": "BachelorDegreeWebhook",
  "name": "Bachelor of Science Webhook"
}

The issued credential will look like:

{
  ...
  "credentialSubject": {
    "id": "did:key:z6MkuHcPf3jhFwGso9agCvbvpzsbn6gHtYYNudXxHjQW1zQd#z6MkuHcPf3jhFwGso9agCvbvpzsbn6gHtYYNudXxHjQW1zQd",
    "degree": {
      "type": "BachelorDegreeWebhook",
      "name": "Bachelor of Science Webhook"
    }
  },
  ...
}

#EBSI Specific Functions

The EBSI trust framework mandates a specific timestamp format for issued credentials, which differs from the one generated by other timestamp functions in walt.id. To ensure compliance, we have developed a set of timestamp data functions specifically for issuing EBSI-compliant credentials which you can find below.

#EBSI Timestamp

<ebsi-timestamp> to get the current timestamp in ISO 8601 format YYYY-MM-DDThh:mm:ssZ

#EBSI Timestamp In

<ebsi-timestamp-in:duration> to get a future date by providing the duration as an argument (e.g., "timestamp-in:365d" for one year from now). Returned timestamp will be in ISO 8601 format YYYY-MM-DDThh:mm:ssZZ

Issue mDLs via OID4VC Ecosystems