Managing Data Validators

A Data Validator is an on-chain contract that inspects the contents of a credential — not just whether it exists. Attaching a Data Validator to an identity-validation policy lets you enforce rules on credential data, such as "only allow investors whose credential says they are in the US or Canada" or "reject any account whose credential country is on a sanctions list".

This guide covers creating, configuring, and attaching Data Validators. For the credential side of the workflow — linking a data schema to a credential type and issuing credentials with data — see Managing Credential Types and Managing Credentials.

How Data Validators fit in

Identity-validation policies — the CredentialRegistryIdentityValidatorPolicy and the GroupedIdentityValidatorPolicy — resolve a caller's address to a CCID and check credentials from credential sources. Each credential source can optionally reference a Data Validator.

When a credential source has a Data Validator configured, the policy performs an extra step at transaction time:

1. Resolve the account's CCID and confirm the credential exists (attestation check).
2. Fetch the credential's stored credentialData.
3. Call the Data Validator's validateCredentialData(...), which returns true or false.

The credential passes only if both the attestation check and the data check succeed. Without a Data Validator, the source is attestation-only — it confirms the credential exists but ignores its contents.

The AllowDenyList Data Validator

ACE provides a pre-built, audited Data Validator implementation: the AllowDenyList Data Validator. It validates a credential payload against an allowlist and a denylist, with an optional restriction by credential type. Its rules are:

• If the denylist contains any value present in the credential, validation fails.
• If the allowlist is non-empty, at least one value in the credential must be allowlisted; otherwise validation fails.
• If the allowlist is empty, the allow check passes (deny-only mode).

The first use case shipped on top of this implementation is jurisdiction control using ISO 3166-1 alpha-2 country codes (e.g., US, CA, GB). The country codes are the values checked against the allow and deny lists.

Prerequisites

Before creating a Data Validator:

1. A policy engine deployed on your target chains.
2. A credential type linked to a data schema so its credentials carry data — for the jurisdiction use case, the ISO 3166-1 alpha-2 country code schema. See Managing Credential Types.
3. Credentials issued with data against that credential type. See Managing Credentials.

Create a Data Validator

A Data Validator instance is a deployed copy of a Data Validator implementation (such as the AllowDenyList country-code validator), configured with your specific allow and deny lists and scoped to one or more chains — the same shape as a policy instance.

The AllowDenyList (country codes) Data Validator implementation ID is:

2aed366a-38af-4f48-b8e2-8fd1489db9fa

Create a Data Validator instance with a POST request. Provide the implementation ID and, for each chain, the initial_config with your allow and deny lists:

curl -X POST https://ace.api.chain.link/v1/data-validators \
  -H "Content-Type: application/json" \
  -H "Authorization: Apikey <API_KEY>" \
  -d '{
    "name": "Jurisdiction allow/deny",
    "description": "Allow US and CA, deny KP",
    "data_validator_implementation_id": "2aed366a-38af-4f48-b8e2-8fd1489db9fa",
    "onchain_data_validators": [
      {
        "chain_selector": "16015286601757825753",
        "initial_config": {
          "allowlist": [{ "item": "US" }, { "item": "CA" }],
          "denylist": [{ "item": "KP" }],
          "supportedDataTypes": []
        }
      }
    ]
  }'

Each on-chain Data Validator starts in creation_pending status until deployment completes. The response includes the instance id and the on-chain addresses per chain.

Update a Data Validator configuration

You can update the allow and deny lists after deployment without redeploying the validator. Configuration changes use JSON Patch and are version-checked per chain for optimistic concurrency.

Update the configuration with a PATCH request. Supply on_chains with the current_config_version for each chain you are changing:

curl -X PATCH https://ace.api.chain.link/v1/data-validators/<DATA_VALIDATOR_ID>/configs \
  -H "Content-Type: application/json" \
  -H "Authorization: Apikey <API_KEY>" \
  -d '{
    "patches": [
      { "op": "add", "path": "/allowlist/-", "value": "GB" }
    ],
    "on_chains": [
      { "chain_selector": "16015286601757825753", "current_config_version": "0" }
    ]
  }'

The JSON Patch format follows RFC 6902. If the current_config_version does not match the on-chain state, the request is rejected — re-fetch the instance and retry with the current version.

Attach a Data Validator to a credential source

A Data Validator takes effect only when it is referenced by a credential source on an identity-validation policy. Each credential source has a dataValidator field:

• 0x0000000000000000000000000000000000000000 — attestation-only (default). The source checks only that the credential exists.
• A Data Validator address — the source additionally validates credential contents through that validator.

Set the dataValidator field to your deployed Data Validator address when configuring the credential source on your CredentialRegistryIdentityValidatorPolicy or GroupedIdentityValidatorPolicy instance. See Managing Policies — Update policy configuration for how to change a policy instance's configuration.

View Data Validators

List all Data Validators:

curl https://ace.api.chain.link/v1/data-validators \
  -H "Authorization: Apikey <API_KEY>"

To retrieve a specific Data Validator by ID:

curl https://ace.api.chain.link/v1/data-validators/<DATA_VALIDATOR_ID> \
  -H "Authorization: Apikey <API_KEY>"

Archive a Data Validator

Archiving a Data Validator deactivates the instance. Before archiving, detach it from any credential source that references it (set that source's dataValidator back to the zero address).

Archive a Data Validator with a PATCH request:

curl -X PATCH https://ace.api.chain.link/v1/data-validators/<DATA_VALIDATOR_ID> \
  -H "Content-Type: application/json" \
  -H "Authorization: Apikey <API_KEY>" \
  -d '{
    "status": "archived"
  }'

Related pages

• Cross-Chain Identity — Credential data and privacy — attestation-only vs. Data Validator checks
• Managing Credential Types — link a data schema to a credential type
• Managing Credentials — issue credentials with data
• CredentialRegistryIdentityValidatorPolicy — the policy that consumes Data Validators via credential sources
• GroupedIdentityValidatorPolicy — grouped identity validation with routing and Data Validators
• Coordinator API Reference — full API schema