Schema & API — OccBiomechanics

Metadata schema

Each record has the following fields. Four are required: id, title, status, source, plus at least one entry each in tasks and modalities. Everything else is optional — we fill what the source documents.

id: Unique lowercase-hyphenated slug; also the URL of the dataset's page (/datasets/<id>.html).
title: Human-readable dataset title.
status: open = publicly downloadable · restricted = available on request or under a data-use agreement · coming_soon = announced, not yet released.
source: Authors, institution, publication year, and country — ISO 3166-1 alpha-2 codes of where the data was collected (e.g. [US], [FR, DE]); drives the country filter and the Countries count.
access: Canonical landing page URL, DOI, and license. The catalog links out; it does not rehost. Datasets keep their own licenses.
tasks: Occupational tasks performed, from a controlled vocabulary (below). mmh is the umbrella term for manual materials handling.
modalities: What was captured — sensors and data streams, from a controlled vocabulary (below). Derived outputs (pose keypoints, joint angles, activity labels) are not modalities; describe them in description.
subjects: Participant count n, sex split, and age range as reported by the source.
exoskeleton: Present only on exoskeleton-relevant records. Detailed below.
load: Free-text protocol summary: handled loads, task intensity, conditions.
equipment: Capture systems used (mocap brand, EMG system, IMU count and placement…).
sampling: Sampling rate per modality in Hz (video in fps).
formats: File formats distributed, from a controlled vocabulary (below).
description: What was performed, what was captured, and why it is useful (≤600 characters).
tags: Free-form keywords for search.
added: Date the entry was added to this catalog (not the dataset's release date).

Exoskeleton fields

Records that involve an occupational exoskeleton carry an extra exoskeleton object. It is what drives the exoskeleton filters on the catalog page and the grouping on the exoskeleton collection. Datasets with no exoskeleton connection omit the object entirely.

role: Required within the object. evaluation = a device was worn and its effect measured · control_input = collected to develop or control an exoskeleton, with no device worn during capture.
devices: Device names as the source reports them, e.g. Laevo V2.5. Several when a study compares devices.
body_region: Region the device supports — the grouping used on the collection page. For control_input records it is the region the work targets.
actuation: Actuation principle: passive, active, or quasi-passive. Several when a study compares mechanisms.
comparison: Study design in one line, e.g. "With vs. without the exoskeleton, within-subject".
outcomes: Outcome families reported, so evaluations can be compared on what they measured — and so gaps in the literature are visible.

exoskeleton:
  role: evaluation
  devices: ["Laevo V2.5"]
  body_region: [back]
  actuation: [passive]
  comparison: "With vs. without the exoskeleton, four in-bed patient-handling tasks"
  outcomes: [muscle_activity, kinematics, cardiovascular]

These fields are a working proposal, not a settled standard. If your group evaluates occupational exoskeletons and reports measures this schema cannot express, we would like to hear about it — see how to contribute.

Controlled vocabularies

These lists are generated from the JSON Schema at build time, so they always match what validation accepts.

status: open coming_soon restricted
tasks: lifting lowering carrying pushing pulling holding reaching squatting walking assembly mmh
modalities: mocap imu force_plate pressure emg physiological video egocentric_video depth survey
formats: c3d trc mot sto csv json mp4 mat edf bag npz
setting: lab field mixed
exoskeleton.role: evaluation control_input
exoskeleton.body_region: back shoulder knee hip ankle neck wrist full_body
exoskeleton.actuation: passive active quasi_passive
exoskeleton.outcomes: muscle_activity kinematics kinetics metabolic cardiovascular task_performance subjective discomfort
model.category: assessment-method biomechanical vision wearable
model.status: released coming_soon

Model library schema

Entries in the models library follow a smaller record, validated against its own JSON Schema. Four fields are required: id, title, source, category, plus at least one entry in links (only coming_soon entries may omit links). The library links out; it does not rehost code or weights.

id: Unique lowercase-hyphenated slug; also the card's anchor on the models page (models.html#model-<id>).
title: Human-readable model or method name.
category: Primary form of the model, judged by its main contribution — the grouping on the models page. assessment-method = observational methods, psychophysical tables, and exposure equations (an equation derived from video measurements still belongs here) · biomechanical = physical/physiological predictive models: spine loading, muscle fatigue, metabolic cost · vision = models consuming video, images, or skeleton sequences · wearable = models driven by IMU, insole, or biosensor signals (sensor-fusion models with a wearable core belong here).
status: released = the paper and/or code is public (default) · coming_soon = announced but not yet published.
source: Authors, institution, and publication year of the founding paper.
links: paper is the canonical landing page (usually the DOI resolver) · doi · code when a repository is released · preprint when the paper is paywalled · record for an institutional record or a companion/updated paper · website when the method ships as software.
code_license: SPDX-style license of the released code; omitted when no code is released.
domain: Occupational context the model was built for.
inputs / outputs: What the model consumes and what it produces.
related_datasets: ids of catalog datasets the model was trained on or is otherwise tied to.
description · tags · added: As in the dataset schema.

The compiled library is models.json, same shape as the catalog. Example: list wearable-sensor models with released code:

models = requests.get("https://occbiomechanics.org/models.json").json()
for m in models["models"]:
    if m["category"] == "wearable" and m.get("links", {}).get("code"):
        print(m["id"], "->", m["links"]["code"])

JSON API

The whole catalog is compiled into one static JSON file. Fetch it directly — it is CORS-friendly, requires no authentication, and its shape is stable:

curl https://occbiomechanics.org/catalog.json

Example: list all open datasets that include EMG, in Python:

import requests

catalog = requests.get("https://occbiomechanics.org/catalog.json").json()
for d in catalog["datasets"]:
    if d["status"] == "open" and "emg" in d["modalities"]:
        print(d["id"], "->", d["access"]["url"])

Response shape: {"generated_from", "count", "datasets": [ ... ]}, where each element of datasets is one metadata record with the fields documented above. Released datasets are also described with schema.org/Dataset JSON-LD on their pages for Google Dataset Search.

Example: list every exoskeleton evaluation with the device and the outcomes it measured:

for d in catalog["datasets"]:
    exo = d.get("exoskeleton")
    if exo and exo["role"] == "evaluation":
        print(d["id"], "|", ", ".join(exo.get("devices", [])), "|", ", ".join(exo.get("outcomes", [])))

Contribute

Know a public dataset, model, or analysis tool we should index? Email the link and a short description to dy266@njit.edu — we will fill in the metadata against this schema and credit the suggestion. Sending the fields already filled in is welcome but not expected.

We are also looking for collaborators — labs sharing data, groups running exoskeleton evaluations, and researchers building open analysis tools. See how to contribute.