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

string

required

UUID of the organization creating the schema.

Request body

string

required

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

string

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

object

required

The schema definition. The structure depends on type.

Show schemaPayload for type: INDY

string

required

Name of the schema, for example "EmployeeCredential".

string

required

Semantic version string, for example "1.0".

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.

string

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

Show schemaPayload for type: JSON (W3C)

string

required

Name of the schema.

string

required

Human-readable description of the schema’s purpose.

string

required

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

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

object

Hide properties

string

Platform-internal schema record ID.

string

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

string

Schema name.

string

Schema version.

string[]

List of attribute names registered on the ledger.

string

UUID of the user who created the schema.

string

The DID used to publish the schema.

string

UUID of the owning organization.

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
        }
      ]
    }
  }'

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": "JSON",
    "schemaPayload": {
      "schemaName": "UniversityDegree",
      "description": "Schema for issuing university degree credentials",
      "schemaType": "POLYGON_W3C",
      "attributes": [
        {
          "attributeName": "studentName",
          "displayName": "Student Name",
          "schemaDataType": "string",
          "isRequired": true,
          "minLength": 1,
          "maxLength": 100
        },
        {
          "attributeName": "degree",
          "displayName": "Degree",
          "schemaDataType": "string",
          "isRequired": true,
          "enum": ["Bachelor of Science", "Master of Science", "Doctor of Philosophy"]
        },
        {
          "attributeName": "graduationYear",
          "displayName": "Graduation Year",
          "schemaDataType": "number",
          "isRequired": true,
          "minimum": 1900,
          "maximum": 2100
        }
      ]
    }
  }'

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

string

required

UUID of the organization.

Query parameters

number

Page to retrieve. Min 1. Defaults to 1.

number

Records per page. Min 1. Defaults to 10.

string

Free-text search across schema names.

string

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

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

string

required

UUID of the organization.

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

string

required

UUID of the organization.

string

required

The ledger schema ID.

Query parameters

number

Page to retrieve. Min 1. Defaults to 1.

number

Records per page. Min 1. Defaults to 10.

string

Free-text search.

string

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

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

​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

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