Open Scale Definition (OSD) — Format Specification

1. Overview

OSD (Open Scale Definition) is a JSON-based format for encoding psychological and behavioral measurement scales in a structured, machine-readable form. A scale is defined by a definition file ({CODE}.json) that captures structure, items, dimensions, and scoring rules, and one or more translation files ({CODE}.{lang}.json) that supply all display strings in a given language. For distribution and external hosting, these are combined into a single OSD bundle ({CODE}.osd).

The format is designed to be platform-neutral: the same definition files are read by PEBL (the desktop runner), the web-based scale runner, conversion tools that export to REDCap / LimeSurvey / Qualtrics, and any custom implementation that follows this specification.

Key design principles:

• Separation of structure from language: the .json definition never contains display strings directly; all text passes through translation keys.
• Flat translation files: the .{lang}.json file is a simple key/value object, easy to edit in any text editor or import into a translation management system.
• Explicit scoring: reverse-coding and dimension membership are declared in the definition, not inferred from item order.
• Forward-compatible: unknown keys are silently ignored, so new runners can add fields without breaking existing definitions.
• Single-file distribution: the .osd bundle combines the definition and all translations into one file for easy hosting — point the web runner directly at it with one URL.

2. File Naming & Directory Structure

Each scale lives in its own subdirectory under scales/. The directory name must match the scale code exactly.

scales/
  {CODE}/
    {CODE}.osd           <-- scale definition + translations (single JSON file)
    screenshot.png       <-- (optional) screenshot shown in the catalogue
    README.md            <-- (optional) description and usage notes
    LICENSE.txt          <-- (optional) license evidence

CODE Conventions

• Uppercase letters, digits, and hyphens only. No spaces.
• Use the established abbreviation for well-known scales: PHQ9, GAD7, SF36, BDI2.
• If no abbreviation exists, invent a short descriptive code and document it in scale_info.abbreviation.
• Examples of valid codes: PHQ9, MOSSLP, IPIP-Big5-50, EAS3.

Language Codes

Translation keys within the translations object use ISO 639-1 two-letter language codes: en, de, fr, es, nl, etc. An English translation ("en") is required. Additional languages are optional and are embedded in the same .osd file.

The .osd Format

A .osd file is a plain JSON file that packages the scale definition and all translations into a single document. It is the standard format used throughout OpenScales: in the repository, the web runner, the PEBL desktop launcher, and PEBLHub. A researcher hosting a scale on their own website needs only one file, and the web runner can be pointed at it with a single URL.

Bundle structure

{
  "osd_version": "1.0",
  "definition": {
    /* complete contents of {CODE}.json */
  },
  "translations": {
    "en": { /* complete contents of {CODE}.en.json */ },
    "de": { /* complete contents of {CODE}.de.json */ },
    "fr": { /* ... */ }
  }
}

Using a .osd file with the web runner

Because a .osd file is plain JSON, it can be fetched from any URL that serves it with CORS headers — including OSF, GitHub raw, GitLab raw, and ordinary web hosting. No special server configuration is required.

Direct URL — share a single link that runs the scale straight from your hosted file:

<!-- OSF -->
scale-runner.html?osd=https://osf.io/abc123/download&lang=en

<!-- GitHub raw -->
scale-runner.html?osd=https://raw.githubusercontent.com/user/repo/main/GAD7.osd

<!-- GitLab raw -->
scale-runner.html?osd=https://gitlab.com/user/repo/-/raw/main/GAD7.osd

<!-- Personal/lab website -->
scale-runner.html?osd=https://lab.example.org/scales/GAD7.osd&lang=fr

JavaScript API:

ScaleRunner.mount(container, {
  osdURL:      'https://osf.io/abc123/download',
  language:    'de',        // falls back to 'en' if 'de' not present in bundle
  participant: participantId,
  onComplete:  handleResult,
});

Using a .osd file with PEBL

The PEBL launcher reads .osd files directly and unpacks them to create a valid PEBL experiment. Once unpacked, you can use the standard PEBL schemes for translations (language files) and parameter-setting (parameter files). Place the .osd file in your PEBL scales/ directory and select it from the launcher's ScaleBuilder interface.

The .osd file is also available for download directly from each scale's page on this website. The MIME type for serving .osd files is application/json; no special server configuration is required.

3. Top-Level Keys of the Definition Object

These keys appear inside the "definition" object of the .osd file.

4. scale_info Object

Metadata that identifies the scale and satisfies attribution and licensing requirements.

Example

"scale_info": {
  "name":         "Patient Health Questionnaire-9",
  "code":         "PHQ9",
  "abbreviation": "PHQ-9",
  "description":  "9-item depression screening tool measuring symptom severity over the past 2 weeks. Scores range from 0 to 27.",
  "citation":     "Kroenke, K., Spitzer, R. L., & Williams, J. B. (2001). The PHQ-9: Validity of a brief depression severity measure. Journal of General Internal Medicine, 16(9), 606-613. https://doi.org/10.1046/j.1525-1497.2001.016009606.x",
  "license":      "Public Domain",
  "version":      "1.0",
  "url":          "https://doi.org/10.1046/j.1525-1497.2001.016009606.x"
}

5. likert_options Object

Defines the single shared response scale applied to every item whose type is "likert". If the scale has no likert-type items (all items are multi, short, number, etc.), set likert_options to null.

Example — PHQ-9 (4-point, 0-based)

"likert_options": {
  "points":        4,
  "min":           0,
  "max":           3,
  "labels":        ["likert_1", "likert_2", "likert_3", "likert_4"],
  "question_head": "question_head"
}

6. parameters Object

An optional object that declares named runtime parameters. Parameters can be overridden at launch time via URL query strings (?param_NAME=value) or via the launcher configuration dialog, without editing the definition file. Each key is the parameter name; the value is a parameter descriptor object.

Reserved Parameter Names

Runners give these parameter names special treatment in addition to normal parameter substitution. Scales that require specific behavior should declare these in their parameters block with the appropriate default.

Example

"parameters": {
  "shuffle_questions": {
    "type":        "boolean",
    "default":     false,
    "description": "Randomize item presentation order"
  },
  "show_header": {
    "type":        "boolean",
    "default":     false,
    "description": "Hide scale title to avoid response bias"
  },
  "system_name": {
    "type":        "string",
    "default":     "the system",
    "description": "Name of the system being evaluated (inserted into item text)"
  },
  "scale_version": {
    "type":        "choice",
    "default":     "full",
    "options":     ["full", "short", "screening"],
    "description": "Which version of the scale to administer"
  }
}

Parameters are overridden at runtime via URL query strings (?param_shuffle_questions=1) or via launcher configuration. Parameters are referenced by name in the enabled_param field of a dimension (see Section 7). Parameter values can also be substituted into item text using {param_name} syntax in translation strings.

7. dimensions Array

Each element describes one scored subscale. The array determines what subscale scores are computed and reported. Items may belong to zero, one, or more dimensions; dimension membership is declared in the scoring object, not here.

Example — SF-36 multi-dimension excerpt

"dimensions": [
  {
    "id":           "pf",
    "name":         "Physical Functioning",
    "abbreviation": "PF",
    "description":  "Extent to which health limits physical activities. Range: 10–30 (higher = less limitation).",
    "enabled_param": null
  },
  {
    "id":           "ewb",
    "name":         "Emotional Well-Being",
    "abbreviation": "EWB",
    "description":  "Extent of anxiety and depression. Range: 5–30 (higher = better mental health).",
    "enabled_param": null
  }
]

8. items Array

The ordered list of every item presented to the participant, including instruction screens, image displays, and scored questions. Items are shown in array order unless branching conditions redirect flow.

8a. Common Fields (All Item Types)

8b. Item Type Reference

8c. options for multi / multicheck / dropdown / rank

Each element of the options array is an object with two required fields:

8d. visible_when (Skip Logic)

An optional condition object that controls whether this item is shown. The item appears only when the condition evaluates to true; it is skipped (and its response recorded as "NA") when the condition is false. A missing or null visible_when means always show.

Simple condition (previous item's response)

{
  "id": "followup1",
  "text_key": "followup1",
  "type": "likert",
  "visible_when": {
    "item": "screen1",
    "operator": "equals",
    "value": 1
  }
}

Condition on a parameter value

{
  "visible_when": {
    "parameter": "show_followup",
    "operator": "equals",
    "value": true
  }
}

Compound conditions

Use "all" (logical AND) or "any" (logical OR) to combine conditions:

{
  "visible_when": {
    "all": [
      { "item": "q1", "operator": "equals", "value": "Yes" },
      { "parameter": "show_followup", "operator": "equals", "value": true }
    ]
  }
}

Operators

8e. Sections

A section item creates a logical boundary within the items list. All items after a section marker (up to the next marker) belong to that section. Sections control randomization scope, skip logic, and optional back-navigation behavior.

{
  "items": [
    { "id": "inst1", "type": "inst", "text_key": "intro_text" },
    {
      "id": "sec_demographics",
      "type": "section",
      "title_key": "demographics_title"
    },
    { "id": "q1", "type": "short", "text_key": "q1" },
    { "id": "q2", "type": "multi",  "text_key": "q2", "options": [...] },
    {
      "id": "sec_main",
      "type": "section",
      "title_key": "main_title",
      "randomize": { "method": "shuffle", "fixed": ["q3"] }
    },
    { "id": "q3", "type": "likert", "text_key": "q3" },
    { "id": "q4", "type": "likert", "text_key": "q4" }
  ]
}

Implicit first section: Items appearing before the first section marker are in an implicit unnamed section (always shown, revisable by default). To control its properties, place a section marker as the very first item.

8f. Input Validation

For short and long items, a validation object specifies constraints checked before advancing. Multiple constraints may coexist; each has a paired *_error key naming the translation string for the error message shown when that constraint fails.

{
  "id": "age",
  "type": "short",
  "text_key": "age_question",
  "validation": {
    "number_min": 0,
    "number_min_error": "age_too_low",
    "number_max": 150,
    "number_max_error": "age_too_high"
  }
}

{
  "id": "bio",
  "type": "long",
  "text_key": "bio_question",
  "validation": {
    "min_words": 10,
    "min_words_error": "bio_too_short",
    "max_length": 500,
    "max_length_error": "bio_too_long"
  }
}

{
  "id": "hobbies",
  "type": "multicheck",
  "text_key": "hobbies_question",
  "options": [...],
  "validation": {
    "min_selected": 1,
    "min_selected_error": "hobbies_min",
    "max_selected": 3,
    "max_selected_error": "hobbies_max"
  }
}

Item Examples

// A standard likert item
{ "id": "phq1", "text_key": "phq1", "type": "likert" }

// A multi item with custom options (pre-reversed for scoring)
{
  "id": "sf36_q11b",
  "text_key": "sf36_q11b",
  "type": "multi",
  "options": [
    { "text_key": "sf36_hp1", "value": 5 },
    { "text_key": "sf36_hp2", "value": 4 },
    { "text_key": "sf36_hp3", "value": 3 },
    { "text_key": "sf36_hp4", "value": 2 },
    { "text_key": "sf36_hp5", "value": 1 }
  ]
}

// An instruction screen (not scored)
{ "id": "sf36_inst1", "text_key": "sf36_inst1", "type": "inst" }

// A number item with constraints
{
  "id": "age",
  "text_key": "age_question",
  "type": "number",
  "min": 0,
  "max": 120,
  "step": 1
}

// An item shown only when a prior item equals 1
{
  "id": "followup1",
  "text_key": "followup1",
  "type": "likert",
  "visible_when": { "item": "screen1", "operator": "equals", "value": 1 }
}

// A section marker with shuffle (keeps q3 in place)
{
  "id": "sec_main",
  "type": "section",
  "title_key": "main_title",
  "randomize": { "method": "shuffle", "fixed": ["q3"] }
}

9. scoring Object

Keyed by dimension id. Each value is a scoring definition object specifying which items contribute to the dimension score and how they are aggregated.

Scoring Methods

Scoring Calculation

For a likert item with item_coding: 1: contribution = response value.

For a likert item with item_coding: -1: contribution = likert_options.min + likert_options.max − response.

For sum_coded: dimension score = sum of all item contributions.
For mean_coded: dimension score = mean of all item contributions.
For max / min: dimension score = maximum/minimum response across all forward-coded inputs (useful for scoring symptom domains as the worst of several alternative items, e.g. the QIDS-SR sleep subscale).

Using scores for higher-order aggregation

Some scales compute a total score by summing subscale scores rather than raw items. Use the scores field to reference already-computed dimension scores:

"scoring": {
  "sleep": {
    "method": "max",
    "items": ["item_falling_asleep", "item_sleep_night", "item_waking_up", "item_sleeping_too_much"],
    "item_coding": {
      "item_falling_asleep": 1, "item_sleep_night": 1,
      "item_waking_up": 1, "item_sleeping_too_much": 1
    }
  },
  "QIDS_total": {
    "method": "sum_coded",
    "scores": ["sleep", "sad_mood", "appetite_weight", "concentration",
               "self_view", "death_suicide", "interest", "energy", "psychomotor"],
    "item_coding": {
      "sleep": 1, "sad_mood": 1, "appetite_weight": 1, "concentration": 1,
      "self_view": 1, "death_suicide": 1, "interest": 1, "energy": 1, "psychomotor": 1
    },
    "description": "Sum of 9 symptom domain scores (0–27)"
  }
}

9a. norms Object

An optional object containing an array of threshold objects used by the runner and report template to display interpretation labels (e.g. "Minimal", "Mild", "Moderate") alongside the score.

"norms": {
  "thresholds": [
    { "min": 0,  "max": 4,  "label": "Minimal" },
    { "min": 5,  "max": 9,  "label": "Mild" },
    { "min": 10, "max": 14, "label": "Moderate" },
    { "min": 15, "max": 19, "label": "Moderately Severe" },
    { "min": 20, "max": 27, "label": "Severe" }
  ]
}

Each threshold's min and max are inclusive. Thresholds should be listed in ascending order and must cover the full possible score range without gaps or overlaps. The label is plain text (not a translation key) so it appears directly in reports.

Scoring Example — PHQ-9

"scoring": {
  "depression": {
    "method": "sum_coded",
    "items": ["phq1","phq2","phq3","phq4","phq5","phq6","phq7","phq8","phq9"],
    "item_coding": {
      "phq1": 1, "phq2": 1, "phq3": 1, "phq4": 1, "phq5": 1,
      "phq6": 1, "phq7": 1, "phq8": 1, "phq9": 1
    },
    "description": "Sum of all items (0–27). Severity: 0-4 minimal, 5-9 mild, 10-14 moderate, 15-19 moderately severe, 20-27 severe.",
    "norms": {
      "thresholds": [
        { "min": 0,  "max": 4,  "label": "Minimal" },
        { "min": 5,  "max": 9,  "label": "Mild" },
        { "min": 10, "max": 14, "label": "Moderate" },
        { "min": 15, "max": 19, "label": "Moderately Severe" },
        { "min": 20, "max": 27, "label": "Severe" }
      ]
    }
  }
}

Scoring Example — SF-36 (mixed forward/reverse coding)

"ef": {
  "method": "sum_coded",
  "items": ["sf36_q9a", "sf36_q9e", "sf36_q9g", "sf36_q9i"],
  "description": "Energy/Fatigue: sum of 4 items (range 4–24; higher = more energy).",
  "item_coding": {
    "sf36_q9a": -1,
    "sf36_q9e": -1,
    "sf36_q9g":  1,
    "sf36_q9i":  1
  }
}

10. report Object

Configures the HTML report generated after scale completion and available for download from the data dashboard.

Example

"report": {
  "template":    "standard",
  "include":     ["timestamp", "completion_time", "dimension_scores"],
  "header":      "PHQ-9 Depression Severity Report. Scores range from 0 to 27.",
  "footer_refs": [
    "Kroenke, K., Spitzer, R. L., & Williams, J. B. (2001). The PHQ-9. Journal of General Internal Medicine, 16(9), 606-613."
  ]
}

11. data_output Object

Controls how output data files are named and what columns they contain. All fields are optional; omitting data_output uses runner defaults.

Example

"data_output": {
  "individual_file": "PHQ9-{subnum}.csv",
  "pooled_file":     "PHQ9-pooled.csv",
  "report_file":     "PHQ9-report-{subnum}.html",
  "columns":         "subnum,order,timestamp,question_id,text_key,dimension,coding,response,rt",
  "pooled_columns":  ""
}

12. Translations (translations Object)

The translations object sits at the root level of the .osd file (alongside osd_version and definition). It is a flat JSON object per language, mapping string keys to translated display strings. Every key referenced in the definition must have an entry for the chosen language.

Rules

• Each language is keyed by its ISO 639-1 code: "en", "de", etc.
• All values are strings. HTML tags are allowed: <b>, <em>, <i>, <br>, <a href="…">.
• Every text_key in items, every key in likert_options.labels, likert_options.question_head, and every text_key in options arrays must be present.
• The key "debrief" (or the key named in scale_info.debrief_key) must be present. Its value is the message shown to the participant on completion.
• English ("en") is required. Additional languages are optional but encouraged.
• Keys not referenced by the definition are ignored.

Example — PHQ-9 English translations

{
  "likert_1":     "not at all",
  "likert_2":     "several days",
  "likert_3":     "more than half the days",
  "likert_4":     "nearly every day",
  "question_head": "Over the <b>last 2 weeks</b>, how often have you been bothered by any of the following problems?",
  "phq1":  "Little interest or pleasure in doing things",
  "phq2":  "Feeling down, depressed, or hopeless",
  "phq3":  "Trouble falling or staying asleep, or sleeping too much",
  "phq4":  "Feeling tired or having little energy",
  "phq5":  "Poor appetite or overeating",
  "phq6":  "Feeling bad about yourself — or that you are a failure or have let yourself or your family down",
  "phq7":  "Trouble concentrating on things, such as reading the newspaper or watching television",
  "phq8":  "Moving or speaking so slowly that other people could have noticed? Or the opposite — being so fidgety or restless that you have been moving around a lot more than usual",
  "phq9":  "Thoughts that you would be better off dead or of hurting yourself in some way",
  "debrief": "Thank you for completing this questionnaire."
}

13. Complete Minimal Example

A fully working OSD definition for a fictional 3-item scale: the Example Anxiety Screen (EAS3). This demonstrates the minimum viable structure: 3 likert items, 1 dimension, sum-coded scoring, and norms.

scales/EAS3/EAS3.osd

{
  "osd_version": "1.0",
  "definition": {
    "scale_info": {
      "name":        "Example Anxiety Screen",
      "code":        "EAS3",
      "abbreviation": "EAS-3",
      "description": "A fictional 3-item anxiety screening scale for demonstration purposes.",
      "citation":    "Author, A. B. (2024). The EAS-3: A demonstration scale. Example Journal, 1(1), 1-5.",
      "license":     "CC0",
      "version":     "1.0"
    },
    "implementation": {
      "author": "Shane T. Mueller",
      "organization": "OpenScales Project",
      "date": "2026-04-01",
      "license": "CC BY 4.0",
      "license_url": "https://creativecommons.org/licenses/by/4.0/"
    },
    "likert_options": {
      "points": 3,
      "min":    0,
      "max":    2,
      "labels": ["eas_never", "eas_sometimes", "eas_often"],
      "question_head": "eas_head"
    },
    "dimensions": [
      {
        "id":          "anxiety",
        "name":        "Anxiety Severity",
        "description": "Sum of all 3 items. Range 0–6; higher = greater anxiety."
      }
    ],
    "items": [
      { "id": "eas_inst", "text_key": "eas_inst", "type": "inst" },
      { "id": "eas1", "text_key": "eas1", "type": "likert" },
      { "id": "eas2", "text_key": "eas2", "type": "likert" },
      { "id": "eas3", "text_key": "eas3", "type": "likert" }
    ],
    "scoring": {
      "anxiety": {
        "method": "sum_coded",
        "items":  ["eas1", "eas2", "eas3"],
        "item_coding": { "eas1": 1, "eas2": 1, "eas3": 1 },
        "description": "Sum of all items (range 0–6).",
        "norms": {
          "thresholds": [
            { "min": 0, "max": 2, "label": "Minimal" },
            { "min": 3, "max": 4, "label": "Mild" },
            { "min": 5, "max": 6, "label": "Moderate to Severe" }
          ]
        }
      }
    }
  },
  "translations": {
    "en": {
      "eas_head":      "Over the <b>past week</b>, how often have you experienced the following?",
      "eas_never":     "never",
      "eas_sometimes": "sometimes",
      "eas_often":     "often",
      "eas_inst":      "This short questionnaire asks about feelings of anxiety you may have experienced recently. There are no right or wrong answers.",
      "eas1":          "Felt nervous, anxious, or on edge",
      "eas2":          "Been unable to stop or control worrying",
      "eas3":          "Felt a sense of dread about what might happen",
      "debrief":       "Thank you for completing the Example Anxiety Screen."
    }
  }
}

14. Versioning & Compatibility Notes

• scale_info.version tracks the version of the individual scale definition file (e.g. when item wording or scoring is corrected), not the OSD format version.
• The OSD format itself is at version 1.x. Future versions will maintain backwards compatibility: new optional keys may be added, but existing required keys will not be removed or renamed in a 1.x release.
• Unknown top-level keys are silently ignored by compliant parsers. This means implementations can add custom extension keys (e.g. "_notes") without breaking other runners.
• Minimum required keys for a valid definition: scale_info (with name and code), likert_options (or null), dimensions, items, and scoring.
• Validation tool: Run python3 tools/validate_scale.py scales/YOURCODE/ to check that all required keys are present, all text_key values have translation entries, and all scoring item references resolve to valid item ids.

Format Version History