Skip to main content

Configuring Data Types

Overview​

Data types define how the system validates and processes credential data. The configuration requirements depend on your role in the credential ecosystem:

  • As an issuer or verifier, data types validate input during credential creation and verify claims during presentation. You configure validation parameters like patterns and min/max values, then assign configured data types to claims in credential schemas.
  • As a holder, data types control how your system extracts and interprets credential data when receiving credentials from issuers. You must configure extraction behavior to accept credentials into your wallet.

This guide covers how to configure data types for both scenarios. For a complete reference of available data types and their parameters, see the data types reference.

Understanding data types by use case​

Issuing and verifying credentials​

When you issue credentials, data types validate the input data before encoding it into the credential. When you verify credentials, data types validate the presented claims against your requirements.

Configuration for issuance and verification focuses on validation parameters:

  • Validation rules: Use parameters like pattern for regex matching, min/max for ranges, and formats for date/datetime requirements
  • User experience: Configure UI parameters like placeholder, autocomplete, and supportedInputMode to improve the issuance form experience.
  • Error handling: Set custom error messages to guide users when validation fails.

These parameters are defined in the params section of each data type. See Configuring for issuance and verification for guidance.

Holding credentials​

When the system receives credentials from external issuers, it extracts and interprets the credential's data types. This process is different from issuance and verification because you do not control the credential schema, but instead adapt to whatever format the issuer used.

The system identifies credentials using schema type identifiers (such as the vct field of SD-JWT VCs or the "DocType" of ISO mdocs). When a credential with a new identifier is received, the system extracts its schema and data type information. This extracted schema information is stored and reused for data validation of all future credentials with the same identifier. Additionally the extracted data types provide hints for displaying credentials in the wallet.

To enable credential holding, you must configure holder.valueExtraction for your data types. Without this configuration, the system cannot accept credentials using providers of type OPENID4VCI_FINAL1. See Configuring for issuance and verification for guidance.

Configuring data types by use case​

Configuring for issuance and verification​

Data type configuration involves creating named instances based on the system's base types (for example STRING, NUMBER, DATE, etc.). Each instance defines validation rules and UI behavior that will be used when the data type is referenced in credential schemas.

You must configure at least one instance of each base type you plan to use. When creating a credential or proof schema, you reference these configured instances by name.

Basic structure​

datatype:
  EMAIL:
    display: "datatype.email"
    type: "STRING"
    order: 110
    params:
      public:
        pattern: '^[\w\-\.]+@([\w\-]+\.)+[\w\-]{2,4}$'
        placeholder: "abc@abc.com"
        autocomplete: true
        supportedInputMode: TEXT
        error:
          en: "Please enter a valid email address"
          de: "Bitte geben Sie eine gültige E-Mail-Adresse ein"

Key configuration elements​

Validation parameters control how data is validated during issuance and verification:

  • pattern: Regex pattern for string validation
  • min/max: Range limits for numbers and dates
  • formats: Date/datetime format requirements
  • accept: Allowed MIME types for files
  • fileSize: Maximum file size in bytes

UI parameters improve the user experience during credential issuance:

  • supportedInputMode: Specifies the input element type (e.g., TEXT, DATE_PICKER, FILE_UPLOAD)
  • placeholder: Hint text shown in empty fields
  • autocomplete: Enables browser autocomplete
  • showAs: Display mode for images
  • error: Custom error messages (supports internationalization)

Multiple instances of the same base type​

You can create multiple instances that use the same base type but have different validation rules. For instance, both EMAIL and a generic instance of type: "STRING", or both BIRTH_DATE and a general DATE instance:

datatype:
  STRING:
    display: "datatype.string"
    type: "STRING"
    order: 100
    params:
      public:
        supportedInputMode: TEXT
  EMAIL:
    display: "datatype.email"
    type: "STRING"
    order: 110
    params:
      public:
        pattern: '^[\w\-\.]+@([\w\-]+\.)+[\w\-]{2,4}$'
        placeholder: "abc@abc.com"
        autocomplete: true
        supportedInputMode: TEXT
        error:
          en: "Please enter a valid email address"
  BIRTH_DATE:
    display: "datatype.birth_date"
    type: "DATE"
    order: 310
    params:
      public:
        formats: ["date"]
        preferredFormat: "date"
        min: 1900-01-01
        max: "NOW"
        supportedInputMode: DATE_PICKER
        error:
          en: "Please choose a date between 1900-01-01 and today"
  DATE:
    display: "datatype.date"
    type: "DATE"
    order: 310
    params:
      public:
        formats: ["date", "datetime"]
        preferredFormat: "datetime"
        supportedInputMode: DATE_PICKER

Each instance can have different validation rules, UI parameters, and display names while sharing the same underlying base type.

Configuring for holder value extraction​

When your system receives credentials as a holder it extracts data type information from the schema. You control this extraction behavior using the holder.valueExtraction parameter.

How extraction works​

The extraction process operates in two tiers:

  1. Primary extraction(ENABLED): Data type providers in this tier attempt extraction first. The process is unordered – if any provider successfully identifies and extracts the claim data type, that type is used immediately.

  2. Fallback extraction(ENABLED_FALLBACK): If all ENABLED providers fail to extract the data type, the system tries providers marked as ENABLED_FALLBACK. These should be broader, more permissive types.

  3. Disabled (DISABLED): The default state. Data types with no value extraction enabled are not used for extraction.

Understanding data type capabilities​

To help you understand which data types can extract which formats, each base type has capabilities that map it to CBOR and JSON types. You can view these capabilities in the GET /api/config/v1 response:

"datatype": {
    "DATE": {
      "capabilities": {
        "supportedCborTypes": [
          "T_DATE",
          "FULL_DATE"
        ],
        "supportedJsonTypes": [
          "STRING"
        ]
      },
    },
}
hint

CBOR is used by ISO mdoc credentials, and JSON is used by all other supported credential formats.

Configuring extraction priority​

Configure extraction in the params.[private/public].holder section:

datatype:
  STRING:
    display: "datatype.string"
    type: "STRING"
    order: 100
    params:
      private:
        holder:
          valueExtraction: ENABLED_FALLBACK
  DATE:
    display: "datatype.date"
    type: "DATE"
    order: 300
    params:
      private:
        holder:
          valueExtraction: ENABLED

Best practices for extraction configuration​

If extraction is too strict and a future credential with the same schema identifier contains slightly different data, your system won't be able to accept it.

  • Use broad types as fallbacks: Configure ENABLED_FALLBACK on base types like STRING, NUMBER, and BOOLEAN. These serve as safety nets when more specific extraction fails.
  • Use specific types for primary extractions: Configure ENABLED on types like DATE and PICTURE that have clear format requirements.
datatype:
  STRING:
    display: "datatype.string"
    type: "STRING"
    order: 100
    params:
      private:
        holder:
          valueExtraction: ENABLED_FALLBACK
  NUMBER:
    display: "datatype.number"
    type: "NUMBER"
    order: 200
    params:
      private:
        holder:
          valueExtraction: ENABLED_FALLBACK
  DATE:
    display: "datatype.date"
    type: "DATE"
    order: 300
    params:
      private:
        holder:
          valueExtraction: ENABLED
  PICTURE:
    display: "datatype.picture"
    type: "PICTURE"
    order: 400
    params:
      private:
        holder:
          valueExtraction: ENABLED
  MDL_PICTURE:
    display: "datatype.mdlPicture"
    type: "PICTURE"
    order: 402
    params:
      private:
        holder:
          valueExtraction: ENABLED
  SWIYU_PICTURE:
    display:
      en: "Picture (SWIYU)"
      de: "Bild (SWIYU)"
    type: "SWIYU_PICTURE"
    order: 403
    params:
      private:
        holder:
          valueExtraction: ENABLED
  OBJECT:
    display: "datatype.object"
    type: "OBJECT"
    order: 500
    params: null
  BOOLEAN:
    display: "datatype.boolean"
    type: "BOOLEAN"
    order: 301
    params:
      private:
        holder:
          valueExtraction: ENABLED_FALLBACK
  ARRAY:
    display: "datatype.array"
    type: "ARRAY"
    order: 101
    params: null