{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://fidetest.de/ptf.schema.json",
  "title": "Psychometric Test Format (PTF) Specification",
  "version": "2.0.0",
  "description": "Standardized JSON specification for digital psychological and clinical questionnaires, scoring rules, norms, and diagnostic interpretations.",
  "type": "object",
  "required": ["meta", "items"],
  "properties": {
    "$schema": {
      "type": "string",
      "description": "URI pointing to this JSON Schema definition."
    },
    "meta": {
      "type": "object",
      "description": "Metadata describing the psychometric test instrument.",
      "required": ["name"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Full official title of the questionnaire (e.g., 'Beck Depression Inventory-II')."
        },
        "abbreviation": {
          "type": "string",
          "description": "Short code or acronym (e.g., 'BDI-II', 'PHQ-9', 'GAD-7')."
        },
        "description": {
          "type": "string",
          "description": "Comprehensive description of what the test measures, its theoretical background, and diagnostic purpose."
        },
        "short_description": {
          "type": "string",
          "description": "Brief 1-2 sentence summary."
        },
        "version": {
          "type": "string",
          "default": "1.0.0",
          "description": "Version of this specific digitized PTF questionnaire."
        },
        "schema_version": {
          "type": "string",
          "default": "2.0.0",
          "description": "PTF schema version used."
        },
        "language": {
          "type": "string",
          "default": "de",
          "description": "ISO 639-1 two-letter language code (e.g., 'de', 'en', 'es')."
        },
        "authors": {
          "type": "array",
          "description": "Original test creators, translators, or digital adaptors.",
          "items": {
            "type": "object",
            "required": ["name"],
            "properties": {
              "name": { "type": "string" },
              "affiliation": { "type": "string" },
              "orcid": { "type": "string" }
            }
          }
        },
        "citation": {
          "type": "string",
          "description": "Official scientific citation or manual reference."
        },
        "license": {
          "type": "object",
          "properties": {
            "type": { "type": "string", "description": "e.g., 'open-access', 'public-domain', 'proprietary', 'cc-by-4.0'" },
            "notice": { "type": "string" },
            "url": { "type": "string" }
          }
        },
        "target_audience": {
          "type": "string",
          "description": "Target population, e.g., 'Erwachsene ab 18 Jahren', 'Kinder und Jugendliche (12-17)'."
        },
        "duration_minutes": {
          "type": "integer",
          "description": "Estimated typical completion time in minutes."
        },
        "rater": {
          "type": "string",
          "enum": ["self", "clinician", "caregiver", "teacher", "observer"],
          "default": "self"
        },
        "tags": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Classification tags (e.g., ['Depression', 'Screening', 'Erwachsene'])."
        },
        "evidence": {
          "type": "object",
          "description": "Psychometric quality criteria (validity, reliability, norms).",
          "properties": {
            "reliability": { "type": "string", "description": "Internal consistency, retest reliability (e.g. 'Cronbachs Alpha = 0.89')." },
            "validity": { "type": "string", "description": "Construct and criterion validity summary." },
            "norms_description": { "type": "string", "description": "Information regarding sample size and standardization." }
          }
        }
      }
    },
    "items": {
      "type": "array",
      "description": "List of all questionnaire items, instructions, and response elements.",
      "items": {
        "type": "object",
        "required": ["id", "type", "text"],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for this item (e.g., 'item_1', 'bdi_13', 'info_intro')."
          },
          "type": {
            "type": "string",
            "enum": ["radio", "scale", "slider", "checkbox", "multiselect", "text", "info"],
            "description": "Input element type. Use 'radio' for single-choice Likert, 'info' for section instructions, 'scale' for discrete ratings."
          },
          "text": {
            "type": "string",
            "description": "The item stem or instruction statement presented to the respondent."
          },
          "required": {
            "type": "boolean",
            "default": true
          },
          "options": {
            "type": "array",
            "description": "Selectable answer choices for radio/scale/checkbox items.",
            "items": {
              "type": "object",
              "required": ["label", "score"],
              "properties": {
                "label": { "type": "string", "description": "Text displayed to respondent." },
                "score": { "type": "number", "description": "Numeric point value assigned to this option for scoring." },
                "value": { "description": "Raw underlying value (if different from score)." }
              }
            }
          },
          "subscale": {
            "type": "string",
            "description": "Subscale key this item belongs to (e.g., 'somatic', 'cognitive')."
          },
          "no_score": {
            "type": "boolean",
            "default": false,
            "description": "If true, item is excluded from total score calculation."
          }
        }
      }
    },
    "scoring": {
      "type": "object",
      "description": "Algorithmic rules for calculating total score, subscales, and cut-off severity interpretations.",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["sum", "mean", "custom"],
          "default": "sum"
        },
        "min_score": { "type": "number" },
        "max_score": { "type": "number" },
        "subscales": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["id", "name", "items"],
            "properties": {
              "id": { "type": "string" },
              "name": { "type": "string" },
              "items": { "type": "array", "items": { "type": "string" } },
              "description": { "type": "string" }
            }
          }
        },
        "cutoffs": {
          "type": "array",
          "description": "Diagnostic severity intervals and clinical recommendations.",
          "items": {
            "type": "object",
            "required": ["min", "max", "label"],
            "properties": {
              "min": { "type": "number" },
              "max": { "type": "number" },
              "label": { "type": "string", "description": "e.g., 'Minimal / Keine Depression', 'Mittelschwere Symptomatik'" },
              "severity": { "type": "string", "enum": ["none", "low", "mild", "moderate", "severe", "critical"] },
              "color": { "type": "string", "description": "Hex or theme color for report rendering (e.g., '#10b981', '#f59e0b', '#ef4444')." },
              "description": { "type": "string", "description": "Detailed clinical interpretation and next steps." }
            }
          }
        }
      }
    },
    "norms": {
      "type": "array",
      "description": "Embedded standardization tables (T-scores, Stanine, Percentiles) by demographic group.",
      "items": {
        "type": "object",
        "required": ["name", "table"],
        "properties": {
          "name": { "type": "string", "description": "Demographic group (e.g., 'Gesamtstichprobe', 'Männer 18-39')." },
          "sample_size": { "type": "integer" },
          "table": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["raw_score"],
              "properties": {
                "raw_score": { "type": "number" },
                "percentile": { "type": "number" },
                "t_score": { "type": "number" },
                "stanine": { "type": "number" },
                "z_score": { "type": "number" }
              }
            }
          }
        }
      }
    },
    "extensions": {
      "type": "object",
      "description": "Optional scientific or software-specific extensions."
    }
  }
}