GakuNin RDM API TypeScript Client

TypeScript client library for the GakuNin RDM API.

The GakuNin RDM API follows the Open Science Framework (OSF) API v2 and provides additional APIs for accessing project metadata and file metadata. This library extends osf-api-v2-typescript with GRDM-specific functionality.

Features

• Full access to all 22 OSF API v2 resources (inherited from OsfClient)
• GRDM project metadata retrieval via v2 API (projectMetadata, draftProjectMetadata)
• GRDM file metadata retrieval and update via v1 API (fileMetadata)
• Multi-schema support with type-safe access for both file metadata and project metadata:
  • Schema ①: 公的資金による研究データのメタデータ (SCHEMA_ID_PUBLIC_FUNDING)
  • Schema ②: ムーンショット目標2データベース（未病DB）のメタデータ (SCHEMA_ID_MS2_MIBYODB)
  • File metadata type guard functions: isPublicFundingSchema, isMs2MibyoDbSchema
  • Project metadata discriminated union: GrdmParsedMeta (narrow via schemaType)
• Subfolder navigation via grdmFiles.listByPath() and grdmFiles.listByPathPaginated()
• Custom fetch injection for v1 API requests — enables proxy-based CORS workarounds in browser frontends
• Automatic v1BaseUrl inference from baseUrl
• Automatic unwrapping of registered_meta { value, extra } wrappers
• Automatic parsing of grdm-files JSON strings into typed objects
• CJS / ESM / UMD build outputs

Installation

npm install grdm-api-typescript

Quick Start

import { GrdmClient } from 'grdm-api-typescript';

const client = new GrdmClient({ token: 'your-personal-access-token' });

// Fetch project metadata for a node
const metaList = await client.projectMetadata.listByNode('abc12');
console.log(metaList.data[0].grdmMeta?.projectNameJa);

// Fetch file metadata for a project
const activeSchema = await client.fileMetadata.getActiveMetadata('abc12', 'osfstorage/README.md');
console.log(activeSchema);

Configuration

GrdmClient accepts a GrdmClientConfig object:

Option	Type	Default	Description
token	string	—	Personal access token for authentication
baseUrl	string	https://api.rdm.nii.ac.jp/v2/	Base URL for the v2 API
v1BaseUrl	string	Auto-inferred from baseUrl	Base URL for the v1 API. May be a relative path when fetch is also provided.
allowedHosts	string[]	—	Additional allowed hosts for HTTP requests
fetch	typeof fetch	—	Custom fetch function for v1 API requests (e.g. for proxy-based CORS workarounds)

v1BaseUrl is automatically inferred from baseUrl when omitted. For example, https://api.rdm.nii.ac.jp/v2/ becomes https://rdm.nii.ac.jp/api/v1.

// Default (production)
const client = new GrdmClient({ token: 'your-token' });

// Custom base URL (e.g., staging environment)
const client = new GrdmClient({
  token: 'your-token',
  baseUrl: 'https://staging.rdm.example.com/v2/',
  // v1BaseUrl is auto-inferred from baseUrl
});

// Proxy-based CORS workaround (browser frontend)
const grdmProxyFetch: typeof fetch = (input, init) =>
  fetch((input as string).replace('https://rdm.nii.ac.jp/api/v1', '/grdm-v1-api'), init);

const client = new GrdmClient({
  token: 'your-token',
  v1BaseUrl: 'https://rdm.nii.ac.jp/api/v1',
  fetch: grdmProxyFetch,
});

API Reference

client.projectMetadata

Accesses the GRDM project metadata via the v2 API.

listByNode(nodeId, params?)

Fetches the list of registrations for a node and parses the GRDM metadata.

const result = await client.projectMetadata.listByNode('abc12');

for (const item of result.data) {
  console.log(item.grdmMeta?.projectNameJa);  // e.g. 'プロジェクト名'
  console.log(item.grdmMeta?.funder);
  console.log(item.grdmMeta?.grdmFiles);      // GrdmRegisteredFile[]
}

getById(registrationId)

Fetches a single registration by ID and parses the GRDM metadata.

const item = await client.projectMetadata.getById('reg123');
console.log(item.grdmMeta?.projectNameEn);

Parsed grdmMeta fields

Field	Type	Source key in registered_meta
funder	string	funder
programNameJa	string	program-name-ja
programNameEn	string	program-name-en
projectNameJa	string	project-name-ja
projectNameEn	string	project-name-en
japanGrantNumber	string	japan-grant-number
fundingStreamCode	string	funding-stream-code
projectResearchField	string	project-research-field
registrationSupplement	string	registration_supplement
grdmFiles	GrdmRegisteredFile[]	grdm-files (JSON string, auto-parsed)

The { value, extra } wrapper in registered_meta is automatically unwrapped.

---

client.draftProjectMetadata

Accesses GRDM project metadata via the v2 draft registrations API. Supports both schema ① and schema ②.

listByNode(nodeId, params?)

const result = await client.draftProjectMetadata.listByNode('abc12');

for (const draft of result.data) {
  const meta = draft.grdmMeta;
  if (!meta) continue;

  if (meta.schemaType === 'public-funding') {
    console.log(meta.funder);
    console.log(meta.japanGrantNumber);
  } else if (meta.schemaType === 'ms2-mibyodb') {
    console.log(meta.projectName);
    console.log(meta.dataCreators?.[0].nameEn);
  }
}

getById(draftId)

const draft = await client.draftProjectMetadata.getById('draft123');
if (draft.grdmMeta?.schemaType === 'ms2-mibyodb') {
  console.log(draft.grdmMeta.titleOfDataset);
}

Parsed grdmMeta fields — schema ① ('public-funding')

Same fields as client.projectMetadata (see above).

Parsed grdmMeta fields — schema ② ('ms2-mibyodb', Ms2ProjectRegisteredMeta)

Field	Type	Source key in registration_metadata
projectName	string	project-name
titleOfDataset	string	title-of-dataset
titleOfDatasetEn	string	title-of-dataset-en
dataCreators	Ms2Person[]	data-creator (JSON string, auto-parsed)
dataManagers	Ms2Person[]	data-manager (JSON string, auto-parsed)
keywords	Ms2Keyword[]	keywords (JSON string, auto-parsed)
datasetResearchField	string	dataset-research-field
accessRights	string	access-rights
dataPolicyFree	string	data-policy-free
dataPolicyLicense	string	data-policy-license
informedConsent	string	informed-consent
ethicsReviewCommitteeApproval	string	ethics-review-committee-approval
purposeOfExperiment	string	purpose-of-experiment
descriptionOfExperimentalCondition	string	description-of-experimental-condition
analysisType	string[]	Analysis-type
targetTypeOfAcquiredData	string	target-type-of-acquired-data
availabilityOfCommercialUse	string	availability-of-commercial-use
conflictOfInterest	string	conflict-of-interest-Yes-or-No
necessityOfContactAndPermission	string	necessity-of-contact-and-permission
namesToBeIncludedInAcknowledgments	string	names-to-be-included-in-the-acknowledgments
repositoryInformation	string	repository-information
dateRegisteredInMetadata	string	date-registered-in-metadata
disclaimerVersion	string	disclaimer-version
grdmFiles	GrdmRegisteredFile[]	grdm-files (JSON string, auto-parsed)
checklists	Record<string, string[]>	Checklist1–Checklist13

Ms2Person: { name, nameEn, belonging, belongingEn, contact } Ms2Keyword: { filename, filenameEn }

---

client.fileMetadata

Accesses the GRDM file metadata via the v1 API.

getByProject(projectId)

Fetches all file metadata for a project.

const response = await client.fileMetadata.getByProject('abc12');
console.log(response.data.attributes.files);

findFileByPath(projectId, path)

Finds a specific file's metadata by its storage path.

const file = await client.fileMetadata.findFileByPath('abc12', 'osfstorage/data.csv');
console.log(file?.items);

getActiveMetadata(projectId, path)

Returns the currently active metadata schema for a file as GrdmFileMetadataSchema | undefined.

The data property is typed as GrdmFileMetadataData (a union of all supported schemas). Use the type guard functions to narrow to the specific schema type before accessing fields, or cast explicitly with as.

import {
  isPublicFundingSchema,
  isMs2MibyoDbSchema,
} from 'grdm-api-typescript';

const schema = await client.fileMetadata.getActiveMetadata('abc12', 'osfstorage/data.csv');

// Type guard: narrows to PublicFundingFileMetadataSchema
if (schema && isPublicFundingSchema(schema)) {
  console.log(schema.data['grdm-file:title-ja']?.value);
  console.log(schema.data['grdm-file:access-rights']?.value);
}

// Type guard: narrows to Ms2MibyoDbFileMetadataSchema
if (schema && isMs2MibyoDbSchema(schema)) {
  console.log(schema.data['grdm-file:d-msr-object-of-measurement-jp']?.value);
  console.log(schema.data['grdm-file:d-msr-data-type-en']?.value);
}

updateFileMetadata(projectId, fileItem)

Updates the metadata of a specific file via a PATCH request to the GRDM v1 API. The target file URL is derived from fileItem.path (e.g., "osfstorage/README.md"). Returns Promise<void> and throws on non-2xx responses.

const fileItem = await client.fileMetadata.findFileByPath('abc12', 'osfstorage/data.csv');

if (fileItem) {
  const updated = {
    ...fileItem,
    items: fileItem.items?.map((schema) =>
      schema.active
        ? {
            ...schema,
            data: {
              ...schema.data,
              'grdm-file:data-description-ja': {
                value: 'Updated description',
                extra: [],
                comments: [],
              },
            },
          }
        : schema,
    ) ?? [],
  };

  await client.fileMetadata.updateFileMetadata('abc12', updated);
}

---

client.grdmFiles

Subfolder navigation within a node's storage provider (v2 Files API).

listByPath(nodeId, provider, folderPath, params?)

Lists files and folders inside a specific subfolder. The leading / in folderPath is stripped automatically.

// List files inside the subfolder at path '/abc123/'
const result = await client.grdmFiles.listByPath('abc12', 'osfstorage', '/abc123/');

for (const item of result.data) {
  console.log(item.kind, item.name);  // 'file' | 'folder'
}

listByPathPaginated(nodeId, provider, folderPath, params?)

Same as listByPath but returns a PaginatedResult for automatic multi-page iteration.

const paged = await client.grdmFiles.listByPathPaginated('abc12', 'osfstorage', '/abc123/');

// Iterate over every item across all pages
for await (const item of paged.items()) {
  console.log(item.name);
}

// Or collect everything at once
const all = await paged.toArray();

---

OSF Resources (inherited)

All 22 OSF API v2 resources from OsfClient are available directly on GrdmClient:

// Nodes
const nodes = await client.nodes.list();

// Files
const files = await client.files.list('abc12');

// Users, Registrations, Institutions, etc.
const user = await client.users.getMe();

For the full list of OSF resources, see the osf-api-v2-typescript documentation.

Examples

The examples/ directory contains sample scripts demonstrating common use cases:

Example	Description
basic_usage.ts	Basic operations: user info, node list, project metadata, file metadata
fetch_project_and_file_metadata.ts	Detailed project and file metadata retrieval for a specific node
file_metadata_via_proxy.ts	File metadata retrieval via a reverse proxy using custom fetch (CORS workaround)
list_all_projects.ts	Paginated listing of all accessible projects using PaginatedResult
file_operations.ts	File listing, subfolder navigation, download, upload, update, and delete
update_grdm_file_metadata.ts	Update a file's metadata via updateFileMetadata, then restore the original value

Run examples with ts-node:

# Basic usage
GRDM_TOKEN=<your-token> npx ts-node examples/basic_usage.ts

# Fetch metadata for a specific node
GRDM_TOKEN=<your-token> GRDM_NODE_ID=<node-id> npx ts-node examples/fetch_project_and_file_metadata.ts

# File metadata via proxy (CORS workaround)
GRDM_TOKEN=<your-token> GRDM_NODE_ID=<node-id> npx ts-node examples/file_metadata_via_proxy.ts

# List all projects
GRDM_TOKEN=<your-token> npx ts-node examples/list_all_projects.ts

# File operations (optionally pass a nodeId)
GRDM_TOKEN=<your-token> npx ts-node examples/file_operations.ts [nodeId]

# Update file metadata (write and restore a test value)
GRDM_TOKEN=<your-token> GRDM_NODE_ID=<node-id> GRDM_FILE_ID=<file-id> npx ts-node examples/update_grdm_file_metadata.ts

See examples/README.md for details on each example and available environment variables.

Development

Install dependencies

npm install

Build (CJS / ESM / UMD)

npm run build

Run tests

npm run test

Lint

npm run lint

Format

npm run format

CI / CD

This project uses GitHub Actions for continuous integration and delivery.

Workflow	Trigger	Description
CI	Push / PR to main	Lint, type-check, test, and build on Node.js 20, 22, and 24
CD	Push of v* tag	Run tests and publish to npm with provenance

To release a new version, create and push a version tag:

npm version patch   # or minor / major
git push --follow-tags

License

Apache License 2.0. See LICENSE for details.