Credential Schemas

Credential schemas define the structure and validation rules for Verifiable Credentials in IDA. Schemas are registered on the ADI blockchain via the Schema Registry smart contract and validated at issuance time.

Schema Lifecycle

Schema Structure

A credential schema in IDA follows the JSON Schema (draft 2020-12) format:

1
{
2
  "id": "urn:uuid:...",
3
  "type": "JsonSchema",
4
  "name": "UniversityDegree",
5
  "version": "1.0",
6
  "author": "did:adi:issuer001",
7
  "created": "2026-03-28T10:00:00Z",
8
  "schema": {
9
    "$schema": "https://json-schema.org/draft/2020-12/schema",
10
    "type": "object",
11
    "required": ["degree", "university", "graduationYear"],
12
    "properties": {
13
      "degree": {
14
        "type": "object",
15
        "required": ["type", "name"],
16
        "properties": {
17
          "type": {
18
            "type": "string",
19
            "enum": ["BachelorDegree", "MasterDegree", "DoctoralDegree"]
20
          },
21
          "name": { "type": "string", "maxLength": 200 },
22
          "university": { "type": "string" },
23
          "graduationYear": { "type": "integer", "minimum": 1900, "maximum": 2100 },
24
          "gpa": { "type": "number", "minimum": 0, "maximum": 4.0 }
25
        }
26
      }
27
    }
28
  }
29
}

Built-in Schema Templates

IDA ships with six built-in schema templates located in packages/api/internal/schemas/.

Education Degree (education_degree.json)

For university and educational institution credentials.

KYC Verification (kyc_verification.json)

For Know Your Customer verification credentials.

Vaccination Record (vaccination_record.json)

For healthcare vaccination credentials.

Address Proof (address_proof.json)

For address verification credentials.

Agent Capability (agent_capability.json)

For AI Agent capability attestation credentials. Attests that an agent possesses specific capabilities as evaluated by a trusted authority.

Agent Delegation (agent_delegation.json)

For AI Agent delegation credentials. Grants specific permissions from a delegator to a delegate agent with constraints and chain-of-delegation support.

Schema Registration

Create Schema via API

$
curl -X POST http://localhost:8080/api/v1/credentials/schemas \
>
  -H "Content-Type: application/json" \
>
  -H "Authorization: ApiKey dev-api-key" \
>
  -d '{
>
    "name": "EmploymentCredential",
>
    "version": "1.0",
>
    "author": "did:adi:issuer001",
>
    "schema": {
>
      "$schema": "https://json-schema.org/draft/2020-12/schema",
>
      "type": "object",
>
      "required": ["employer", "position", "startDate"],
>
      "properties": {
>
        "employer": { "type": "string" },
>
        "position": { "type": "string" },
>
        "startDate": { "type": "string", "format": "date" },
>
        "endDate": { "type": "string", "format": "date" },
>
        "salary": { "type": "number", "minimum": 0 }
>
      }
>
    }
>
  }'

List Schemas

$
curl http://localhost:8080/api/v1/credentials/schemas?page=1&limit=20 \
>
  -H "Authorization: ApiKey dev-api-key"

Get Schema by ID

$
curl http://localhost:8080/api/v1/credentials/schemas/urn:uuid:schema-id \
>
  -H "Authorization: ApiKey dev-api-key"

Schema Versioning

Schemas are immutable once registered. To update a schema, create a new version:

Version 1.1 credentials can be verified against 1.0 verifiers (optional fields ignored). Version 2.0 credentials require updated verifiers.

Schema Validation

When a VC is issued with a schemaId, IDA validates the credentialSubject against the declared schema:

1. All required attributes must be present
2. Attribute types must match the schema definition
3. Enum values must be in the allowed set
4. Numeric values must satisfy min/max constraints
5. String lengths must not exceed defined maximums
6. Nested objects are validated recursively

Validation errors return a 422 Unprocessable Entity with details:

1
{
2
  "error": {
3
    "code": "SCHEMA_VALIDATION_FAILED",
4
    "message": "schema validation failed: graduationYear: required field missing; gpa: value 5.0 exceeds maximum 4.0; "
5
  }
6
}

Custom Schema Creation

Organizations can define custom schemas for any use case. The schema must follow JSON Schema draft 2020-12 and include:

• A type field (usually "object")
• A properties object defining each field’s type and constraints
• A required array listing mandatory fields

The schema is validated at registration time and enforced at credential issuance time when the schemaId is provided in the issuance request.