> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/credebl/platform/llms.txt
> Use this file to discover all available pages before exploring further.

# Schemas

> Create and retrieve credential schemas that define the attribute names and types used in verifiable credentials.

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.

```http theme={null}
Authorization: Bearer <your-jwt-token>
```

## Role-based access

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

## Endpoints

<CardGroup cols={2}>
  <Card title="Create schema" icon="plus" href="/api-reference/credentials/schemas#create-schema">
    `POST /orgs/:orgId/schemas` — Register a new schema on the ledger.
  </Card>

  <Card title="List schemas" icon="list" href="/api-reference/credentials/schemas#list-schemas">
    `GET /orgs/:orgId/schemas` — Retrieve all schemas for an organization.
  </Card>

  <Card title="Get schema" icon="magnifying-glass" href="/api-reference/credentials/schemas#get-schema-by-id">
    `GET /orgs/:orgId/schemas/:schemaId` — Fetch a schema from the ledger by its ID.
  </Card>

  <Card title="Credential definitions by schema" icon="id-card" href="/api-reference/credentials/schemas#credential-definitions-by-schema">
    `GET /orgs/:orgId/schemas/:schemaId/cred-defs` — List credential definitions linked to a schema.
  </Card>
</CardGroup>

***

## 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

<ParamField path="orgId" type="string" required>
  UUID of the organization creating the schema.
</ParamField>

### Request body

<ParamField body="type" type="string" required>
  Schema format. Enum: `INDY` or `JSON` (W3C JSON-LD).
</ParamField>

<ParamField body="alias" type="string">
  Optional human-readable alias for the schema record in the platform database.
</ParamField>

<ParamField body="schemaPayload" type="object" required>
  The schema definition. The structure depends on `type`.

  <Expandable title="schemaPayload for type: INDY">
    <ParamField body="schemaName" type="string" required>
      Name of the schema, for example `"EmployeeCredential"`.
    </ParamField>

    <ParamField body="schemaVersion" type="string" required>
      Semantic version string, for example `"1.0"`.
    </ParamField>

    <ParamField body="attributes" type="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.
    </ParamField>

    <ParamField body="orgDid" type="string">
      Override the organization's DID used to write the schema. Defaults to the org's primary DID.
    </ParamField>
  </Expandable>

  <Expandable title="schemaPayload for type: JSON (W3C)">
    <ParamField body="schemaName" type="string" required>
      Name of the schema.
    </ParamField>

    <ParamField body="description" type="string" required>
      Human-readable description of the schema's purpose.
    </ParamField>

    <ParamField body="schemaType" type="string" required>
      The JSON-LD schema type. Enum: `POLYGON_W3C` (and other supported W3C types).
    </ParamField>

    <ParamField body="attributes" type="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`.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="data" type="object">
  <Expandable title="properties" defaultOpen>
    <ResponseField name="id" type="string">
      Platform-internal schema record ID.
    </ResponseField>

    <ResponseField name="schemaLedgerId" type="string">
      The schema's ID on the ledger, for example `"WgWxqztrNooG92RXvxSTWv:2:EmployeeCredential:1.0"`.
    </ResponseField>

    <ResponseField name="name" type="string">
      Schema name.
    </ResponseField>

    <ResponseField name="version" type="string">
      Schema version.
    </ResponseField>

    <ResponseField name="attributes" type="string[]">
      List of attribute names registered on the ledger.
    </ResponseField>

    <ResponseField name="createdBy" type="string">
      UUID of the user who created the schema.
    </ResponseField>

    <ResponseField name="publisherDid" type="string">
      The DID used to publish the schema.
    </ResponseField>

    <ResponseField name="orgId" type="string">
      UUID of the owning organization.
    </ResponseField>

    <ResponseField name="issuerId" type="string">
      The issuer DID associated with the schema.
    </ResponseField>
  </Expandable>
</ResponseField>

### Examples

<CodeGroup>
  ```bash AnonCreds (Indy) schema theme={null}
  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
          }
        ]
      }
    }'
  ```

  ```bash W3C JSON-LD schema theme={null}
  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
          }
        ]
      }
    }'
  ```
</CodeGroup>

```json 201 response theme={null}
{
  "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

<ParamField path="orgId" type="string" required>
  UUID of the organization.
</ParamField>

### Query parameters

<ParamField query="pageNumber" type="number">
  Page to retrieve. Min `1`. Defaults to `1`.
</ParamField>

<ParamField query="pageSize" type="number">
  Records per page. Min `1`. Defaults to `10`.
</ParamField>

<ParamField query="searchByText" type="string">
  Free-text search across schema names.
</ParamField>

<ParamField query="sortField" type="string">
  Field to sort by. Enum: `createDateTime` (default) and other available sort fields.
</ParamField>

<ParamField query="sortBy" type="string">
  Sort direction. `ASC` or `DESC` (default).
</ParamField>

### Examples

<CodeGroup>
  ```bash curl theme={null}
  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>"
  ```
</CodeGroup>

```json 200 response theme={null}
{
  "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

<ParamField path="orgId" type="string" required>
  UUID of the organization.
</ParamField>

<ParamField path="schemaId" type="string" required>
  The ledger schema ID, for example `"WgWxqztrNooG92RXvxSTWv:2:EmployeeCredential:1.0"`.
</ParamField>

### Examples

<CodeGroup>
  ```bash curl theme={null}
  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>"
  ```
</CodeGroup>

```json 200 response theme={null}
{
  "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

<ParamField path="orgId" type="string" required>
  UUID of the organization.
</ParamField>

<ParamField path="schemaId" type="string" required>
  The ledger schema ID.
</ParamField>

### Query parameters

<ParamField query="pageNumber" type="number">
  Page to retrieve. Min `1`. Defaults to `1`.
</ParamField>

<ParamField query="pageSize" type="number">
  Records per page. Min `1`. Defaults to `10`.
</ParamField>

<ParamField query="searchByText" type="string">
  Free-text search.
</ParamField>

<ParamField query="sortField" type="string">
  Field to sort by. Enum: `createDateTime` (default).
</ParamField>

<ParamField query="sortBy" type="string">
  Sort direction. `ASC` or `DESC` (default).
</ParamField>

### Examples

<CodeGroup>
  ```bash curl theme={null}
  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>"
  ```
</CodeGroup>

```json 200 response theme={null}
{
  "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"
      }
    ]
  }
}
```