More about PEX Query

Learn more about PEX query and how to use it for requesting data from Affinidi Vault.

Requesting data from Affinidi Vault uses the Presentation Exchange (PEX) protocol to define the data requirements of the website for the user to share in the form of a Verifiable Presentation (VP). For the application to trust the data that the user shares you need to define the different set of constraints through input_descriptors of the presentation definition that must be followed and satisfied by the user.

See the different usage of Presentation Definition below to help you understand and define the correct PEX query to request data from Affinidi Vault.

Requesting Emails from a Specific Domain

In this scenario, you aim to accept emails or permit logins only from that particular domain.


{
  "id": "vp_token_with_email_vc",
  "input_descriptors": [
    {
      "id": "email_vc_data",
      "name": "Email VC data",
      "purpose": "Check if data contains necessary fields",
      "constraints": {
        "fields": [
          {
            "path": [
              "$.credentialSubject.email"
            ],
            "purpose": "Email address from specific domain",
            "filter": {
              "type": "string",
              "pattern": "[a-z0-9]+@affinidi.com"
            }
          }
        ]
      }
    }
  ]
}

In the above example, we check if the email address exists in the VC and that the email address value is from a specific domain, affinidi.com. This PEX query enables Affinidi Login flow to restrict logins to particular domains like corporate emails.

Request Data from Specific VC Type

In this scenario, you aim to request data generated from a specific VC type.


{
    "id": "vp_token_with_specific_type",
    "input_descriptors": [
      {
        "id": "email_vc",
        "name": "Email VC",
        "purpose": "we can get vc of email schema",
        "group": ["A"],
        "constraints": {
          "fields": [
            {
              "path": [
                "$.type"
              ],
              "purpose": "Check if VC type is correct",
              "filter": {
                "type": "array",
                "contains": {
                  "type": "string",
                  "pattern": "Email"
                }
              }
            }
          ]
        }
      }
    ]
}

In the above example, we check whether the VC is issued using a specific type. Specifically, the schema should be of type Email. This PEX query is helpful in scenarios where your application expects a clear data structure to prevent parsing failures caused by unrecognized data formats. This particular check is defined in the default Presentation Definition used by Affinidi Login.

Request Data from a Specific Issuer

In this scenario, you aim to ensure that the data retrieved from the user’s Vault originates from a particular issuer. You can meet this requirement by implementing checks based on the specific DID of the issuer within the PEX query.


{
  "id": "vp_token_with_specific_issuer",
  "input_descriptors": [
    {
      "id": "vc_issuer",
      "name": "VC Issuer",
      "purpose": "Check if VC Issuer is Trusted",
      "constraints": {
        "fields": [
          {
            "path": [
              "$.issuer"
            ],
            "purpose": "issuer",
            "filter": {
              "type": "string",
              "pattern": "^did:key:zQ3shtMGCU89kb2RMknNZcYGUcHW8P6Cq3CoQyvoDs7Qqh33N"
            }
          }
        ]
      }
    }
  ]
}

In the above example, we are checking the issuer field in the VC for a specific DID value; in this case, we are checking if Affinidi issues the VC.

Request User Profile from a Specific Country

In this scenario, you aim to accept user profiles from specific demographics (e.g. Country).


{
  "id": "vp_token_with_profile_vc",
  "input_descriptors": [
    {
      "id": "email_vc_data",
      "name": "Email VC data",
      "purpose": "Check if data contains necessary fields and data",
      "constraints": {
        "fields": [
          {
            "path": [
              "$.credentialSubject.address.country"
            ],
            "purpose": "User profile from specific country",
            "filter": {
              "type": "string",
              "pattern": "Singapore"
            }
          }
        ]
      }
    }
  ]
}

In the example above, we verify whether the address object’s country field contains the value Singapore. This PEX query is useful when your application restricts access to specific resources based on the user’s region.

Learn more about customising the Presentation Definition and the ID Token Mapping for Affinidi Login to help you define the query to request additional data from the Vault and provide more constraints to the requested data using this guide.