6. Dataset Registration

Documentation

Tutorials

This tutorial covers registering datasets in the dAIEDGE Middleware for use in AI model training and benchmarking.

Overview

Dataset registration allows you to:

Publish datasets to the blockchain with ownership tracking
Version datasets
Control access to proprietary datasets
Enable dataset discovery for benchmarking
Track dataset usage

Prerequisites

Completed Authentication, Wallet Management, Identity Management, and Role Management tutorials
Active session and wallet
DATASET_OWNER_ROLE and DATASET_OPERATOR_ROLE assigned to your identity (see Role Management)

Required Roles

Dataset Roles

To register and manage datasets, you need the following roles:

Role	Purpose	Required For
`DATASET_OWNER_ROLE`	Register and update datasets	Creating new dataset registrations
`DATASET_OPERATOR_ROLE`	List and view datasets	Listing datasets, getting dataset details

Authorization

You can register datasets if:

Your identity has DATASET_OWNER_ROLE (granted by ADMIN_ROLE)

You can list and view datasets if:

Your identity has DATASET_OPERATOR_ROLE (granted by ADMIN_ROLE)

You can update datasets if:

You own the dataset (registered it), OR
You have DATASET_OPERATOR_ROLE AND are a valid delegate of the dataset owner (via Identity Management)

See the Role Management tutorial to obtain these roles.

Step 1: Register Dataset

Endpoint

POST /api/v1/dataset

Request

curl -X POST https://middleware-daiedge.bisite.usal.es/api/v1/dataset \
  -H "Content-Type: application/json" \
  -H "x-session-id: {SESSION_ID}" \
  -d '{
    "walletId": "0000019d8e3b5c7a9f2d4e6b8a1c3f5e",
    "password": "WalletPass123!",
    "did": "did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
    "name": "ImageNet-1K",
    "description": "1000-class image classification dataset",
    "uri": "https://datasets.example.com/imagenet-1k",
    "version": "1.0.0"
  }'

async with daiedge_middleware_client.ApiClient() as api_client:
    dataset_api = daiedge_middleware_client.RegisterDatasetApi(api_client)
    result = await dataset_api.dataset_post(
        daiedge_middleware_client.RegisterDatasetBody(
            wallet_id="0000019d8e3b5c7a9f2d4e6b8a1c3f5e",
            password="WalletPass123!",
            did="did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
            name="ImageNet-1K",
            description="1000-class image classification dataset",
            uri="https://datasets.example.com/imagenet-1k",
            version="1.0.0",
        )
    )
    print(f"Dataset registered: id={result.id}")

Request Body

Field	Type	Required	Description
`walletId`	string	Yes	Your wallet ID
`password`	string	Yes	Wallet password
`did`	string	Yes	Your identity DID (format: `did:ethr:{network}:0x...`)
`name`	string	Yes	Dataset name (max 255 chars)
`description`	string	Yes	Dataset description (max 255 chars)
`uri`	string	Yes	Dataset location URL (max 255 chars)
`version`	string	Yes	Dataset version (max 255 chars)

Response (200 OK)

{
  "id": "0x7c9a2f1e5b8d4a6c3e9f7b2d5a8c1f4e6b9d3a7c5e2f8b4d1a6c9e3f7b5d2a8c"
}

Returns the dataset ID (bytes32 hash).

Error Responses

Code	Error	Cause
404	`WALLET_NOT_FOUND`	Wallet doesn’t exist
400	`WRONG_PASSWORD`	Wallet password incorrect
400	`INVALID_DID`	Identity address format invalid
400	`INVALID_NAME`	Name empty or > 255 chars
400	`INVALID_DESCRIPTION`	Description empty or > 255 chars
400	`INVALID_URI`	URI empty or > 255 chars
400	`INVALID_VERSION`	Version empty or > 255 chars
403	`INVALID_WALLET`	Wallet doesn’t belong to you
500	`TRANSACTION_ERROR`	Blockchain transaction failed (check you have `DATASET_OWNER_ROLE`)

Step 2: List Datasets

Endpoint

GET /api/v1/dataset?userDID={userDID}&page={page}

Request

curl -X GET "https://middleware-daiedge.bisite.usal.es/api/v1/dataset?userDID=did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7&page=1" \
  -H "x-session-id: {SESSION_ID}"

async with daiedge_middleware_client.ApiClient() as api_client:
    dataset_api = daiedge_middleware_client.RegisterDatasetApi(api_client)
    datasets = await dataset_api.dataset_get(
        user_did="did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
        page=1,
    )
    print(f"total: {datasets.total}")
    for ds in datasets.datasets:
        print(f"id: {ds.id}  name: {ds.name}  version: {ds.version}")

Note: Requires DATASET_OPERATOR_ROLE. The list endpoint filters datasets based on access permissions.

Response (200 OK)

{
  "datasets": [
    {
      "id": "0x7c9a2f1e5b8d4a6c3e9f7b2d5a8c1f4e6b9d3a7c5e2f8b4d1a6c9e3f7b5d2a8c",
      "owner": "did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
      "name": "ImageNet-1K",
      "description": "1000-class image classification dataset",
      "uri": "https://datasets.example.com/imagenet-1k",
      "version": "1.0.0",
      "created": 1697000000000
    }
  ],
  "page": 1,
  "totalPages": 5,
  "total": 120
}

Note: There is no delete endpoint for datasets, once registered, a dataset remains on the blockchain. Use the detail endpoint below to retrieve a specific dataset directly by its ID.

Get Dataset Details

Endpoint

GET /api/v1/dataset/{id}?userDID={userDID}

curl -X GET "https://middleware-daiedge.bisite.usal.es/api/v1/dataset/{DATASET_ID}?userDID=did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7" \
  -H "x-session-id: {SESSION_ID}"

async with daiedge_middleware_client.ApiClient() as api_client:
    dataset_api = daiedge_middleware_client.RegisterDatasetApi(api_client)
    dataset = await dataset_api.dataset_id_get(
        id="{DATASET_ID}",
        user_did="did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
    )
    print(f"owner: {dataset.owner}")
    print(f"name: {dataset.name}  version: {dataset.version}")

Step 3: Update Dataset

Endpoint

POST /api/v1/dataset/{id}

Request

curl -X POST https://middleware-daiedge.bisite.usal.es/api/v1/dataset/{DATASET_ID} \
  -H "Content-Type: application/json" \
  -H "x-session-id: {SESSION_ID}" \
  -d '{
    "walletId": "0000019d8e3b5c7a9f2d4e6b8a1c3f5e",
    "password": "WalletPass123!",
    "did": "did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
    "name": "ImageNet-1K",
    "description": "Updated 1000-class image classification dataset",
    "uri": "https://datasets.example.com/imagenet-1k-v2",
    "version": "2.0.0"
  }'

async with daiedge_middleware_client.ApiClient() as api_client:
    dataset_api = daiedge_middleware_client.RegisterDatasetApi(api_client)
    await dataset_api.dataset_id_post(
        id="{DATASET_ID}",
        request=daiedge_middleware_client.UpdateDatasetBody(
            wallet_id="0000019d8e3b5c7a9f2d4e6b8a1c3f5e",
            password="WalletPass123!",
            did="did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
            name="ImageNet-1K",
            description="Updated 1000-class image classification dataset",
            uri="https://datasets.example.com/imagenet-1k-v2",
            version="2.0.0",
        )
    )
    print("Dataset updated successfully")

Request body fields are the same as Step 1: Register Dataset.

Response (200 OK)

{}

Authorization

You can update a dataset if:

You are the dataset owner (registered it), OR
You have DATASET_OPERATOR_ROLE AND are a valid delegate of the owner (via Identity Management)

Access Control for Datasets

Dataset access control works identically to hardware access control. See Hardware Access Control tutorial for details.

Grant Dataset Access

curl -X POST https://middleware-daiedge.bisite.usal.es/api/v1/access/grant-access \
  -H "Content-Type: application/json" \
  -H "x-session-id: {SESSION_ID}" \
  -d '{
    "walletId": "0000019d8e3b5c7a9f2d4e6b8a1c3f5e",
    "password": "WalletPass123!",
    "userDID": "did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
    "did": "did:ethr:development:0x8Ba1f109551bD432803012645Ac136ddd64DBA72",
    "resourceId": "0x7c9a2f1e5b8d4a6c3e9f7b2d5a8c1f4e6b9d3a7c5e2f8b4d1a6c9e3f7b5d2a8c",
    "resourceType": "dataset",
    "expirationTime": 1735689600,
    "usageLimit": 100,
    "indefinite": false
  }'

async with daiedge_middleware_client.ApiClient() as api_client:
    access_api = daiedge_middleware_client.AccessControlApi(api_client)
    await access_api.access_grant_access_post(
        daiedge_middleware_client.GrantAccessBody(
            wallet_id="0000019d8e3b5c7a9f2d4e6b8a1c3f5e",
            password="WalletPass123!",
            user_did="did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
            did="did:ethr:development:0x8Ba1f109551bD432803012645Ac136ddd64DBA72",
            resource_id="0x7c9a2f1e5b8d4a6c3e9f7b2d5a8c1f4e6b9d3a7c5e2f8b4d1a6c9e3f7b5d2a8c",
            resource_type="dataset",
            expiration_time=1735689600,
            usage_limit=100,
            indefinite=False,
        )
    )
    print("Dataset access granted")

Next Steps

AI Model Registration - Register AI models to use with datasets
Benchmarking - Use datasets in benchmarks

6. Dataset Registration

Overview

Prerequisites

Required Roles

Dataset Roles

Authorization

Step 1: Register Dataset

Endpoint

Request

Request Body

Response (200 OK)

Error Responses

Step 2: List Datasets

Endpoint

Request

Response (200 OK)

Get Dataset Details

Endpoint

Step 3: Update Dataset

Endpoint

Request

Response (200 OK)

Authorization

Access Control for Datasets

Grant Dataset Access

Next Steps

Related Topics