Defining a Dataset Schema

A dataset schema lets you describe the structure of your data before uploading it. Schemas are a feature of V4 datasets and enable:

• Named, typed fields that drive what participants see
• dataset_field items in batch_items that pull dataset values directly into your task layout
• Per-record validation during import (with strict mode)
• Structured metadata and custom task grouping

Creating a dataset with a schema

Pass a schema object when creating a dataset.

$
POST /api/v1/data-collection/datasets

1
{
2
  "name": "AI response evaluation",
3
  "workspace_id": "6278acb09062db3b35bcbeb0",
4
  "schema": {
5
    "strict": true,
6
    "fields": {
7
      "prompt": { "type": "text", "label": "Prompt" },
8
      "source_audio": { "type": "audio_url", "label": "Audio clip" },
9
      "source_video": { "type": "video_url", "label": "Video clip" },
10
      "response_a": { "type": "text", "label": "Response A" },
11
      "response_b": { "type": "text", "label": "Response B" },
12
      "category": { "type": "metadata" }
13
    }
14
  }
15
}

Field types

Audio URL fields

Use audio_url for externally hosted source audio that participants should listen to during a Batch task.

• Prolific does not host source media. audio_url fields must point to audio files hosted outside Prolific.
• URLs must remain valid for the full study duration. The audio URL should stay reachable and accessible from dataset import through participant completion.
• Use direct-file HTTPS URLs only. Manifest-based streaming formats such as .m3u8 and .mpd are not supported.
• Supported audio formats: .mp3, .wav, .aac, and .m4a.
• Access-Control-Allow-Origin (CORS): without it the audio can still play, but the player shows a generic placeholder waveform instead of the decoded waveform preview because waveform generation uses a cross-origin fetch.
• Cache-Control and/or ETag: without cache headers the same file may be downloaded twice — once to decode the waveform and once again for playback.

Video URL fields

Use video_url for externally hosted source video that participants should watch during a Batch task.

• Prolific does not host source media. video_url fields must point to video files hosted outside Prolific.
• URLs must remain valid for the full study duration. The video URL should stay reachable and accessible from dataset import through participant completion.
• Use direct-file HTTPS URLs only. Manifest-based streaming formats such as .m3u8 and .mpd are not supported and are rejected during dataset validation.
• Supported video formats: .mp4, .mov, .webm, and .m4v.
• Access-Control-Allow-Origin (CORS): without it the video can still play, but the player shows a generic placeholder poster frame instead of the real one, because the poster frame is decoded via a cross-origin fetch.
• Cache-Control and/or ETag: without cache headers the same file may be downloaded twice — once to decode the poster frame and once again for playback.

Strict mode

The strict flag controls how missing fields are handled during import.

Schema constraints

• Maximum 200 fields per schema.
• Field keys: 1–128 characters.
• Field labels: maximum 255 characters.
• At most one field of type task_group_id per schema.

Referencing schema fields in the batch layout

Once a dataset with a schema is attached to a batch, you can use dataset_field items in batch_items to display dataset values to participants.

1
{
2
  "batch_items": [
3
    {
4
      "rows": [
5
        {
6
          "columns": [
7
            {
8
              "items": [
9
                { "type": "dataset_field", "field": "prompt" },
10
                { "type": "dataset_field", "field": "response_a" },
11
                { "type": "dataset_field", "field": "response_b" },
12
                {
13
                  "type": "multiple_choice",
14
                  "description": "Which response is more helpful?",
15
                  "answer_limit": 1,
16
                  "options": [
17
                    { "label": "Response A", "value": "a" },
18
                    { "label": "Response B", "value": "b" },
19
                    { "label": "Neither", "value": "neither" }
20
                  ]
21
                }
22
              ]
23
            }
24
          ]
25
        }
26
      ]
27
    }
28
  ]
29
}

Retrieving a dataset with its schema

$
GET /api/v1/data-collection/datasets/{dataset_id}

The response includes the current schema and all import jobs:

1
{
2
  "id": "0192a3b5-e8f9-7a0b-1c2d-3e4f5a6b7c8d",
3
  "name": "AI response evaluation",
4
  "schema_version": 4,
5
  "total_datapoint_count": 1000,
6
  "schema": {
7
    "strict": true,
8
    "fields": {
9
      "prompt": { "type": "text", "label": "Prompt" },
10
      "source_audio": { "type": "audio_url", "label": "Audio clip" },
11
      "source_video": { "type": "video_url", "label": "Video clip" },
12
      "response_a": { "type": "text", "label": "Response A" },
13
      "response_b": { "type": "text", "label": "Response B" },
14
      "category": { "type": "metadata" }
15
    }
16
  },
17
  "imports": [
18
    {
19
      "import_id": "01935c2d-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
20
      "status": "complete",
21
      "accepted_count": 1000
22
    }
23
  ]
24
}