How to Contribute a Scale

OpenScales grows through community contributions. This guide walks you through writing an OSD file, validating the result, and submitting it.

Overview

OpenScales accepts validated, published psychological scales encoded in OSD (Open Scale Definition) format — a structured JSON file that captures items, response options, dimensions, scoring rules, and translations in a single portable bundle.

Before contributing, confirm that the scale meets these criteria:

  • The scale has been published and validated in a peer-reviewed context.
  • You have the right to distribute the items. See the Licensing & Scale Developer Guide for details on licensing options — there are several tiers of participation beyond fully open licenses.
  • You have either authored the scale, have explicit written permission from the rights holder, or can demonstrate that the scale is openly licensed (e.g., published in a CC BY journal with items included).

File Structure

Each scale lives in its own subdirectory under scales/. The directory name must match the scale code exactly (uppercase, no spaces). The primary file format is a .osd bundle that contains the scale definition and all translations in a single file.

scales/
  SCALECODE/
    SCALECODE.osd             <- OSD bundle (definition + translations)
    screenshot.png            <- (Optional) Screenshot of the running scale
    LICENSE.txt               <- (Optional) License evidence or permissions

The scale code should be the widely-used abbreviation in all-caps, e.g. PHQ9, GAD7, IPAQ. If the scale has no established abbreviation, invent a short descriptive one and document it in the abbreviation field.

Alternative: Split Files

You may also submit the definition and translations as separate files. We accept both formats and will merge split files into a single .osd bundle for the final repository. 

scales/
  SCALECODE/
    SCALECODE.json            <- Scale definition (items, dimensions, scoring)
    SCALECODE.en.json         <- English translation strings
    SCALECODE.de.json         <- (Optional) German translation strings

The OSD File (SCALECODE.osd)

The .osd file is a JSON file containing two top-level sections: definition (structure, items, scoring) and translations (all user-facing text, keyed by language). Below is an annotated skeleton showing every major section. 

{
  "osd_version": "1.0",
  "definition": {
    "scale_info": {
      "name":         "Full name of the scale",           // required
      "code":         "SCALECODE",                         // required; matches directory name
      "abbreviation": "SC",                                // short form shown in badges
      "description":  "One-paragraph description …",
      "citation":     "Author, A. (Year). Title. Journal …",
      "license":      "Public Domain",                    // or CC BY 4.0, CC BY-NC 4.0, etc.
      "version":      "1.0",
      "url":          "https://doi.org/…"
    },

    "likert_options": {               // global defaults for likert-type items
      "points":        5,             // number of response options
      "min":           1,             // value of first option
      "max":           5,             // value of last option
      "labels":        ["lbl_1", "lbl_2", "lbl_3", "lbl_4", "lbl_5"],
                                      // translation keys for each point
      "question_head": "question_head"  // translation key for the common question stem
    },

    "dimensions": [
      {
        "id":           "depression",
        "name":         "Depression Severity",
        "abbreviation": "Dep",
        "description":  "Sum of all items"
      }
    ],

    "items": [
      {
        "id":        "item1",         // unique within the scale
        "text_key":  "item1",         // key in the translations block
        "type":      "likert"         // see item types below
      },
      {
        "id":        "item2",
        "text_key":  "item2",
        "type":      "multi",         // multiple-choice (not Likert)
        "options": [
          { "text_key": "opt_yes", "value": 1 },
          { "text_key": "opt_no",  "value": 0 }
        ]
      },
      {
        "id":        "instr1",
        "text_key":  "instructions_text",
        "type":      "inst"           // instruction screen; not scored
      }
    ],
    // Item types: "likert", "multi", "multicheck", "short", "long",
    //             "inst", "vas", "grid"

    "scoring": {
      "depression": {                 // keyed by dimension id
        "method":       "sum_coded",  // or "mean_coded", "weighted_sum", etc.
        "items":        ["item1", "item2"],
        "item_coding":  { "item1": 1, "item2": -1 },
                         // +1 = forward, -1 = reverse-coded, 0 = exclude
        "description":  "Sum of all items (range 0–27).",
        "norms": {
          "thresholds": [
            { "min": 0,  "max": 9,  "label": "Normal" },
            { "min": 10, "max": 27, "label": "Clinical" }
          ]
        }
      }
    }
  },

  "translations": {
    "en": {
      "lbl_1":         "Not at all",
      "lbl_2":         "Several days",
      "lbl_3":         "More than half the days",
      "lbl_4":         "Nearly every day",
      "lbl_5":         "(unused in this example)",
      "question_head": "Over the <b>last 2 weeks</b>, how often …",
      "item1":         "Little interest or pleasure in doing things",
      "item2":         "Feeling down, depressed, or hopeless",
      "opt_yes":       "Yes",
      "opt_no":        "No",
      "instructions_text": "Please answer each question …",
      "debrief":       "Thank you for completing this questionnaire."
    }
  }
}

Translation Keys

Every text_key referenced in items, likert_options.labels, likert_options.question_head, option text_keys, and report must have a corresponding entry in the translations block for each language.

  • HTML is allowed in values — you can use <b>, <em>, <br>, and links.
  • Provide at minimum an English ("en") translation. Additional languages are welcome and can be added as additional keys in the translations object.

Real Example — PHQ9

Here is the items array, scoring block, and English translations from the PHQ9 scale (scales/PHQ9/PHQ9.osd): 

"items": [
  { "id": "phq1", "text_key": "phq1", "type": "likert" },
  { "id": "phq2", "text_key": "phq2", "type": "likert" },
  { "id": "phq3", "text_key": "phq3", "type": "likert" },
  { "id": "phq4", "text_key": "phq4", "type": "likert" },
  { "id": "phq5", "text_key": "phq5", "type": "likert" },
  { "id": "phq6", "text_key": "phq6", "type": "likert" },
  { "id": "phq7", "text_key": "phq7", "type": "likert" },
  { "id": "phq8", "text_key": "phq8", "type": "likert" },
  { "id": "phq9", "text_key": "phq9", "type": "likert" }
],
"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).",
    "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" }
      ]
    }
  }
}
// In "translations" > "en":
"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",
…
"debrief": "Thank you for completing this questionnaire."

Step-by-Step Guide

  1. Review the licensing options. Read the Licensing & Scale Developer Guide to determine which tier fits your situation. For the OpenScales repository, you need a permissive license (Public Domain, CC0, CC BY, or CC BY-NC).
  2. Fork the repository on GitHub. Navigate to github.com/stmueller/OpenScales and click Fork. Clone your fork locally: 
    git clone https://github.com/YOUR_USERNAME/pebl.git
cd pebl
  3. Create the scale directory. Replace YOURCODE with your scale's abbreviation: 
    mkdir scales/openscales/YOURCODE
  4. Write YOURCODE.osd. Use an existing scale (e.g. scales/openscales/PHQ9/PHQ9.osd) as a template. Fill in scale_info, define your items, dimensions, scoring rules, and translations — all in a single .osd file.

    Alternatively, you can write separate YOURCODE.json (definition) and YOURCODE.en.json (translations) files. We will merge them into a .osd bundle before adding to the repository.
  5. Validate the files using the provided tool: 
    python3 tools/validate_scale.py scales/openscales/YOURCODE/
    Fix any errors reported before proceeding.
  6. Test in the browser. Open the runner with your new scale: 
    runner/scale-runner.html?osd=scales/openscales/YOURCODE/YOURCODE.osd&demo=1
    Work through the entire scale and confirm items, response labels, and scoring look correct.
  7. Rebuild the manifest so the website picks up your new scale: 
    python3 tools/build_manifest.py
  8. Submit a Pull Request. Commit your new files, push to your fork, and open a PR against the main repository. In the PR description include:
    • The full name and abbreviation of the scale
    • The original citation
    • License information and a link or copy of the permission evidence
    • Any validation references (psychometric papers)

Don't want to create the file yourself? We can create the .osd file for you from your published materials. Just contact us with the items, response options, scoring rules, and any norms.

Import from Other Formats

If you already have the scale defined in Qualtrics, PsyToolkit, or LimeSurvey format, the conversion tools can generate a starter OSD file that you then review and refine. The generated files will need manual editing — especially scoring rules and norms, which are not captured in most survey platform exports.

Command-Line Importers

# From a Qualtrics .qsf export
python3 tools/convert_from_qualtrics.py survey.qsf --output scales/openscales/YOURCODE/

# From a PsyToolkit survey script
python3 tools/convert_from_psytoolkit.py survey.txt --code YOURCODE --outdir scales/openscales/YOURCODE/

Web Interface

Upload an existing survey file using the Convert page and select "Import to OSD" as the target format. The resulting files can be downloaded and edited locally.

Questions about the contribution process? Contact us at Open a GitHub issue.