Schemas

A schema defines the structure of a verifiable credential — the set of attribute names, their data types, and display metadata. Before you can issue a credential, you need a schema registered on a ledger and a credential definition derived from it. CREDEBL supports two schema formats:

AnonCreds (Indy) — Attributes are a flat list of name/type pairs. Suitable for use with Hyperledger Indy-compatible ledgers.
W3C JSON-LD — Attributes are structured JSON Schema objects supporting rich types (string, number, boolean, array, object) and validation constraints. Used with Polygon and other W3C-compatible ledgers.

Base path

All endpoints are rooted at /orgs/:orgId/schemas.

Authentication

Every endpoint requires a JWT bearer token.

Authorization: Bearer <your-jwt-token>

Role-based access

Operation	Required roles
Create schema	`owner`, `admin`
Read schemas	`owner`, `admin`, `issuer`, `verifier`, `member`

Endpoints

Create schema

POST /orgs/:orgId/schemas — Register a new schema on the ledger.

List schemas

GET /orgs/:orgId/schemas — Retrieve all schemas for an organization.

Get schema

GET /orgs/:orgId/schemas/:schemaId — Fetch a schema from the ledger by its ID.

Credential definitions by schema

GET /orgs/:orgId/schemas/:schemaId/cred-defs — List credential definitions linked to a schema.

Create schema

POST /orgs/:orgId/schemas Register a new schema for an organization. The schema is written to the ledger associated with the organization’s DID. Supports Indy (AnonCreds) and W3C JSON-LD formats. Required roles: owner, admin

Path parameters

orgId

string

required

UUID of the organization creating the schema.

Request body

type

string

required

Schema format. Enum: INDY or JSON (W3C JSON-LD).

alias

string

Optional human-readable alias for the schema record in the platform database.

schemaPayload

object

required

The schema definition. The structure depends on type.

Show schemaPayload for type: INDY

schemaName

string

required

Name of the schema, for example "EmployeeCredential".

schemaVersion

string

required

Semantic version string, for example "1.0".

attributes

object[]

required

Array of attribute definitions. Each attribute must include:

attributeName (string, required) — The attribute key, for example "firstName".
schemaDataType (string, required) — Data type. Enum: string, number, date, datetime.
displayName (string, required) — Human-readable label shown in wallets.
isRequired (boolean, required) — Whether the attribute is mandatory.

orgDid

string

Override the organization’s DID used to write the schema. Defaults to the org’s primary DID.

Show schemaPayload for type: JSON (W3C)

schemaName

string

required

Name of the schema.

description

string

required

Human-readable description of the schema’s purpose.

schemaType

string

required

The JSON-LD schema type. Enum: POLYGON_W3C (and other supported W3C types).

attributes

object[]

required

Array of W3C attribute definitions. Each attribute includes:

attributeName (string, required) — The attribute key.
displayName (string, required) — Human-readable label.
schemaDataType (string, required) — Data type. Enum: string, number, integer, boolean, date, datetime, array, object.
isRequired (boolean, required) — Whether the attribute is mandatory.
description (string, optional) — Attribute description.

String-type attributes additionally support: minLength, maxLength, pattern, enum, contentEncoding, contentMediaType.Number-type attributes additionally support: minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf.Array-type attributes additionally support: minItems, maxItems, uniqueItems, items.Object-type attributes additionally support: minProperties, maxProperties, additionalProperties, required, dependentRequired, properties.

Response

data

object

Hide properties

string

Platform-internal schema record ID.

schemaLedgerId

string

The schema’s ID on the ledger, for example "WgWxqztrNooG92RXvxSTWv:2:EmployeeCredential:1.0".

name

string

Schema name.

version

string

Schema version.

attributes

string[]

List of attribute names registered on the ledger.

createdBy

string

UUID of the user who created the schema.

publisherDid

string

The DID used to publish the schema.

orgId

string

UUID of the owning organization.

issuerId

string

The issuer DID associated with the schema.

Examples

curl --request POST \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/schemas" \
  --header "Authorization: Bearer <your-jwt-token>" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "INDY",
    "alias": "Employee credential schema",
    "schemaPayload": {
      "schemaName": "EmployeeCredential",
      "schemaVersion": "1.0",
      "attributes": [
        {
          "attributeName": "firstName",
          "schemaDataType": "string",
          "displayName": "First Name",
          "isRequired": true
        },
        {
          "attributeName": "lastName",
          "schemaDataType": "string",
          "displayName": "Last Name",
          "isRequired": true
        },
        {
          "attributeName": "employeeId",
          "schemaDataType": "string",
          "displayName": "Employee ID",
          "isRequired": true
        },
        {
          "attributeName": "department",
          "schemaDataType": "string",
          "displayName": "Department",
          "isRequired": false
        },
        {
          "attributeName": "startDate",
          "schemaDataType": "date",
          "displayName": "Start Date",
          "isRequired": true
        }
      ]
    }
  }'

201 response

{
  "statusCode": 201,
  "message": "Schema created successfully",
  "data": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "schemaLedgerId": "WgWxqztrNooG92RXvxSTWv:2:EmployeeCredential:1.0",
    "name": "EmployeeCredential",
    "version": "1.0",
    "attributes": ["firstName", "lastName", "employeeId", "department", "startDate"],
    "publisherDid": "did:indy:WgWxqztrNooG92RXvxSTWv",
    "orgId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "issuerId": "WgWxqztrNooG92RXvxSTWv",
    "createdBy": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"
  }
}

Status	Description
`400 Bad Request`	`orgId` is not a valid UUID, or required fields are missing.
`401 Unauthorized`	Missing or invalid bearer token.
`403 Forbidden`	User does not have `owner` or `admin` role.
`409 Conflict`	A schema with the same name and version already exists on the ledger.

List schemas

GET /orgs/:orgId/schemas Retrieve all schemas belonging to an organization. Supports pagination, full-text search, and sorting. Required roles: owner, admin, issuer, verifier, member

Path parameters

orgId

string

required

UUID of the organization.

Query parameters

pageNumber

number

Page to retrieve. Min 1. Defaults to 1.

pageSize

number

Records per page. Min 1. Defaults to 10.

searchByText

string

Free-text search across schema names.

sortField

string

Field to sort by. Enum: createDateTime (default) and other available sort fields.

sortBy

string

Sort direction. ASC or DESC (default).

Examples

curl --request GET \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/schemas?pageNumber=1&pageSize=20&sortBy=DESC" \
  --header "Authorization: Bearer <your-jwt-token>"

200 response

{
  "statusCode": 200,
  "message": "Schemas fetched successfully",
  "data": {
    "totalItems": 1,
    "hasNextPage": false,
    "data": [
      {
        "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
        "schemaLedgerId": "WgWxqztrNooG92RXvxSTWv:2:EmployeeCredential:1.0",
        "name": "EmployeeCredential",
        "version": "1.0",
        "attributes": ["firstName", "lastName", "employeeId", "department", "startDate"],
        "orgId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "createdAt": "2024-01-15T09:00:00.000Z"
      }
    ]
  }
}

Get schema by ID

GET /orgs/:orgId/schemas/:schemaId Fetch the full schema details from the ledger using its ledger schema ID. Required roles: owner, admin, issuer, verifier, member

Path parameters

orgId

string

required

UUID of the organization.

schemaId

string

required

The ledger schema ID, for example "WgWxqztrNooG92RXvxSTWv:2:EmployeeCredential:1.0".

Examples

curl --request GET \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/schemas/WgWxqztrNooG92RXvxSTWv:2:EmployeeCredential:1.0" \
  --header "Authorization: Bearer <your-jwt-token>"

200 response

{
  "statusCode": 200,
  "message": "Schema fetched successfully",
  "data": {
    "schema": {
      "attrNames": ["firstName", "lastName", "employeeId", "department", "startDate"],
      "name": "EmployeeCredential",
      "version": "1.0",
      "issuerId": "WgWxqztrNooG92RXvxSTWv"
    },
    "schemaId": "WgWxqztrNooG92RXvxSTWv:2:EmployeeCredential:1.0"
  }
}

Status	Description
`400 Bad Request`	`schemaId` is missing or malformed.
`404 Not Found`	Schema not found on the ledger.

Credential definitions by schema

GET /orgs/:orgId/schemas/:schemaId/cred-defs List all credential definitions on the platform that are derived from a given schema. Required roles: owner, admin, issuer, verifier, member

Path parameters

orgId

string

required

UUID of the organization.

schemaId

string

required

The ledger schema ID.

Query parameters

pageNumber

number

Page to retrieve. Min 1. Defaults to 1.

pageSize

number

Records per page. Min 1. Defaults to 10.

searchByText

string

Free-text search.

sortField

string

Field to sort by. Enum: createDateTime (default).

sortBy

string

Sort direction. ASC or DESC (default).

Examples

curl --request GET \
  --url "http://localhost:5000/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/schemas/WgWxqztrNooG92RXvxSTWv:2:EmployeeCredential:1.0/cred-defs" \
  --header "Authorization: Bearer <your-jwt-token>"

200 response

{
  "statusCode": 200,
  "message": "Schema fetched successfully",
  "data": {
    "totalItems": 1,
    "data": [
      {
        "id": "b1e5f231-4c56-7a89-bc01-d234e567f890",
        "credentialDefinitionId": "WgWxqztrNooG92RXvxSTWv:3:CL:123:default",
        "tag": "default",
        "schemaLedgerId": "WgWxqztrNooG92RXvxSTWv:2:EmployeeCredential:1.0",
        "revocable": false,
        "orgId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "createdAt": "2024-01-15T09:30:00.000Z"
      }
    ]
  }
}

Authentication

Organizations

Connections & Credentials

Ecosystem & Wallet

Base path

Authentication

Role-based access

Endpoints

Create schema

List schemas

Get schema

Credential definitions by schema

Create schema

Path parameters

Request body

Response

Examples

List schemas

Path parameters

Query parameters

Examples

Get schema by ID

Path parameters

Examples

Credential definitions by schema

Path parameters

Query parameters

Examples

Build docs developers (and LLMs) love

Authentication

Organizations

Connections & Credentials

Ecosystem & Wallet

​Base path

​Authentication

​Role-based access

​Endpoints

Create schema

List schemas

Get schema

Credential definitions by schema

​Create schema

​Path parameters

​Request body

​Response

​Examples

​List schemas

​Path parameters

​Query parameters

​Examples

​Get schema by ID

​Path parameters

​Examples

​Credential definitions by schema

​Path parameters

​Query parameters

​Examples

Build docs developers (and LLMs) love

Base path

Authentication

Role-based access

Endpoints

Create schema

Path parameters

Request body

Response

Examples

List schemas

Path parameters

Query parameters

Examples

Get schema by ID

Path parameters

Examples

Credential definitions by schema

Path parameters

Query parameters

Examples