Schema Management

A schema defines the shape of a credential — its required fields, types, and validation rules. Schemas are JSON Schema documents (Draft 2020-12). They are stored in the platform’s schemas table and (optionally) anchored on the SchemaRegistry contract for public verifiability.

4.2.1. Browsing the Schema Library ##### When to use

Before you create a custom schema, check whether one already exists. Reusing an existing schema makes your VCs interoperable with verifiers that already know it.

Steps

1. Navigate to /issuer/schemas. 2. Filter by Type, Issuer, Status (draft / anchored).
2. Click any row to inspect.

API

$
curl https://adid.dev/api/v1/credentials/schemas \
>
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response:

1
{
2
  "data":[
3
    { "id":"schema-uuid-1", "name":"UniversityDegree", "version":"1.0", "issuerDid":"did:adi:0xUniv...", "anchored":true },
4
    { "id":"schema-uuid-2", "name":"DriversLicense",   "version":"2.1", "issuerDid":"did:adi:0xDMV...",  "anchored":true }
5
  ],
6
  "total":2
7
}

4.2.2. Creating a Custom Schema ##### When to use

No existing schema fits your domain. You need to define the credential’s required fields and validation rules before you can issue.

Before you begin

• Issuer role.
• A clear specification of the claim (field names, types, constraints).

Steps

1. Navigate to /issuer/schemas and click Create schema.
2. Fill the Schema metadata form:
   • Name — OrganisationMembership.
   • Version — 1.0 (semver).
   • Description — short purpose statement.
   • Type URI — full URI for @type field.
3. Define the JSON Schema body:

   1
   {
   2
     "$schema": "https://json-schema.org/draft/2020-12/schema",
   3
     "type": "object",
   4
     "required": ["membershipId", "tier", "validUntil"],
   5
     "properties": {
   6
       "membershipId": { "type": "string", "minLength": 1 },
   7
       "tier":         { "type": "string", "enum": ["bronze","silver","gold"] },
   8
       "validUntil":   { "type": "string", "format": "date-time" }
   9
     },
   10
     "additionalProperties": false
   11
   }
4. Toggle Anchor on chain if you want the schema hash recorded in the SchemaRegistry (recommended for public-facing schemas; not required for internal use).
5. Click Create. The portal calls POST /api/v1/credentials/schemas (vc.go:28).

API & SDK

$
curl -X POST https://adid.dev/api/v1/credentials/schemas \
>
  -H "Authorization: Bearer $ACCESS_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "name":"OrganisationMembership",
>
    "version":"1.0",
>
    "issuerDid":"did:adi:0xOrg...",
>
    "jsonSchema": { "$schema":"https://json-schema.org/draft/2020-12/schema", "type":"object", "required":["membershipId"], "properties":{"membershipId":{"type":"string"}} },
>
    "anchorOnChain": true
>
  }'

1
// Schema CRUD via SDK is planned for v2.1 — for now, call the REST endpoint directly.
2
const res = await fetch('https://adid.dev/api/v1/credentials/schemas', {
3
  method: 'POST',
4
  headers: {
5
    'Authorization': `Bearer ${accessToken}`,
6
    'Content-Type': 'application/json',
7
  },
8
  body: JSON.stringify({
9
    name: 'OrganisationMembership',
10
    version: '1.0',
11
    issuerDid: 'did:adi:0xOrg...',
12
    jsonSchema: { /* draft 2020-12 */ },
13
    anchorOnChain: true,
14
  }),
15
});
16
const schema = await res.json();

Verify

The schema appears in /issuer/schemas. If anchored, the row shows a chain-link icon; click to view the txHash.

Troubleshooting

4.2.3. Schema Versioning ##### Overview

IDA enforces semver-style versioning on schemas. Once a schema is anchored, its hash is immutable on chain. Changes require a new version (1.0 → 1.1 for backward-compatible additions; 1.0 → 2.0 for breaking changes).

Why it matters

Verifiers and issuers must agree on the schema version. A VC issued under OrganisationMembership@1.0 is not automatically valid against a verifier expecting OrganisationMembership@2.0. Use the version field on the credential’s credentialSchema reference to make this explicit.

How to bump

1. From /issuer/schemas/<schema>, click New version.
2. Make changes, set version: "1.1" or "2.0".
3. Save (and re-anchor if desired).

The platform retains all versions; the issuer chooses which to use at issuance time.

4.2.4. Anchoring a Schema On-Chain ##### When to use

Public-facing or regulated schemas should be anchored so any verifier can check the schema hash matches what’s on chain — preventing tampering by a compromised API.

Steps

1. From the schema detail page, click Anchor on chain (if not already anchored).
2. Wallet prompts for confirmation. Approve.
3. The platform calls registerSchema(schemaId, hash, version, issuerDid) on the SchemaRegistry contract.
4. After receipt, the row’s status becomes anchored with a txHash.

API

The anchor flag is part of the schema body (see §4.2.2). To anchor an existing schema after creation:

$
curl -X POST https://adid.dev/api/v1/credentials/schemas/<id>/anchor \
>
  -H "Authorization: Bearer $ACCESS_TOKEN"

Verify

Query the SchemaRegistry directly via §11.3 — getSchema(schemaId) should return your hash.