Docs/Dataverse Integration
Documentation

Dataverse Integration

Bio-DID-Seq seamlessly integrates with Harvard Dataverse, enabling researchers to leverage decentralized identifiers and IPFS storage while maintaining compatibility with established research data repositories.

Overview

Harvard Dataverse is one of the world's leading open-source research data repository platforms. Bio-DID-Seq bridges the gap between traditional centralized repositories and decentralized storage:

  • Bidirectional Synchronization: Keep data in sync between IPFS and Dataverse
  • DID-DOI Mapping: Link decentralized identifiers with Digital Object Identifiers
  • Enhanced Metadata: Enrich Dataverse metadata with AI-extracted knowledge
  • GDPR Compliance: Maintain privacy controls across both systems
  • Verifiable Provenance: Track data lineage using content addressing

Configuration

typescript
export const dataverseConfig = {
  serverUrl: process.env.DATAVERSE_URL || 'https://dataverse.harvard.edu',
  apiToken: process.env.DATAVERSE_API_TOKEN,
  defaultDataverse: process.env.DATAVERSE_ALIAS || 'bio-did-seq',
  sync: {
    enabled: true,
    interval: '1h',
    conflictResolution: 'latest-wins'
  }
};

API Reference

Create Dataset

typescript
// POST /api/dataverse/dataset
const response = await fetch('/api/dataverse/dataset', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    did: 'did:bio:123456789abcdefghi',
    dataverseAlias: 'research-lab',
    metadata: {
      title: 'CRISPR-Cas9 Gene Editing Dataset',
      authors: [{ name: 'Jane Smith', orcid: '0000-0001-2345-6789' }],
      description: 'Comprehensive dataset from CRISPR experiments...',
      keywords: ['CRISPR', 'gene editing', 'genomics'],
      license: 'CC-BY-4.0'
    }
  })
});

Response:

json
{
  "success": true,
  "data": {
    "datasetId": 12345,
    "persistentId": "doi:10.7910/DVN/EXAMPLE",
    "did": "did:bio:123456789abcdefghi",
    "status": "DRAFT",
    "links": {
      "dataverse": "https://dataverse.harvard.edu/dataset.xhtml?persistentId=doi:10.7910/DVN/EXAMPLE",
      "ipfs": "ipfs://QmXg9Pp2ytZ14xgK35M6iTC2Vz6jR9zYgooNp2UHPTMnPN"
    }
  }
}

Upload Files

The dataset's persistent identifier (its DOI) is part of the path, and the multipart body carries the file plus an optional description:

typescript
// POST /api/dataverse/dataset/file/{persistent_id}
const formData = new FormData();
formData.append('file', file);
formData.append('description', 'Raw sequencing reads');

const persistentId = encodeURIComponent('doi:10.70122/FK2/ABCDEF');

const response = await fetch(
  `/api/dataverse/dataset/file/${persistentId}`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'X-Dataverse-Token': dataverseApiToken,
      'X-Dataverse-Server': 'demo',
    },
    body: formData,
  }
);
Two credentials. Authorization is your Ekayana session token; X-Dataverse-Token is your own Dataverse API token, which the platform never stores. X-Dataverse-Server selects the installation (defaults to demo).

Publish Dataset

typescript
// POST /api/dataverse/dataset/publish
const response = await fetch('/api/dataverse/dataset/publish', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    datasetId: 'doi:10.7910/DVN/EXAMPLE',
    did: 'did:bio:123456789abcdefghi',
    type: 'major',
    updateIPNS: true
  })
});

Link DID to Dataverse DOI

bash
curl -X POST "https://api.ekayana.com/api/did/did:bio:123456789/dataverse" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dataverseDoi": "doi:10.7910/DVN/EXAMPLE",
    "syncMetadata": true,
    "createIPNS": true
  }'

BioAgents Enhancement

When uploading files, BioAgents can automatically extract and enhance metadata:

typescript
async function uploadWithEnhancement(file: File, persistentId: string) {
  const formData = new FormData();
  formData.append('file', file);
  formData.append('description', 'Deposited via Ekayana');

  const response = await fetch(
    `/api/dataverse/dataset/file/${encodeURIComponent(persistentId)}`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'X-Dataverse-Token': dataverseApiToken,
      },
      body: formData,
    }
  );

  return response.json();
}
Metadata extraction and knowledge-graph enrichment run through the BioAgents endpoints as a separate step, not as flags on the deposit call.

Access Control

UCAN-Based Permissions

typescript
async function grantDataverseAccess(
  issuerKeypair: ed25519.EdKeypair,
  recipientDID: string,
  datasetDID: string,
  permissions: ('read' | 'write' | 'admin')[]
) {
  const ucan = await build({
    issuer: issuerKeypair,
    audience: recipientDID,
    lifetimeInSeconds: 30 * 24 * 3600,
    capabilities: permissions.map(p => ({
      with: { scheme: 'did', hierPart: datasetDID },
      can: { namespace: 'dataverse', segments: [p] }
    }))
  });
  
  return encode(ucan);
}

Role Mapping

Bio-DID-Seq RoleDataverse RolePermissions
ownerAdminFull control
contributorContributorAdd/edit files
curatorCuratorEdit metadata
viewerFile DownloaderDownload files

Best Practices

  • Always link DIDs to DOIs for bidirectional discoverability
  • Enable automatic sync for frequently updated datasets
  • Use BioAgents for metadata extraction on research papers
  • Pin files to IPFS as backup for Dataverse content
  • Create IPNS records for mutable dataset references
Protocol Labs StackUCAN Authorization