The Psychological Test Format (.ptf)

2. Positioning Relative to Existing Health Standards

Unlike regulatory clinical trial formats (CDISC ODM) or generic EHR transport layers (HL7 FHIR), PTF is engineered specifically for the complete psychometric lifecycle:

3. Document Hierarchy and Root Object

A PTF Document MUST be a valid JSON object formatted with UTF-8 encoding. The root object contains the following fields:

4. Instrument Metadata Specification (meta)

The meta object encapsulates scientific, legal, and descriptive information regarding the questionnaire instrument.

5. Questionnaire Items and Response Scales (items)

The items array defines the discrete stimulus statements, input modalities, and numeric point weights.

6. Algorithmic Evaluation and Diagnostic Cut-Offs (scoring)

The scoring object declares the mathematical aggregation formula and diagnostic severity boundaries.

"scoring": {
  "type": "sum",
  "min_score": 0,
  "max_score": 27,
  "cutoffs": [
    { "min": 0, "max": 4, "label": "None / Minimal", "severity": "none", "color": "#10b981" },
    { "min": 5, "max": 9, "label": "Mild Depression", "severity": "mild", "color": "#3b82f6" },
    { "min": 10, "max": 14, "label": "Moderate Depression", "severity": "moderate", "color": "#f59e0b" },
    { "min": 15, "max": 19, "label": "Moderately Severe Depression", "severity": "severe", "color": "#f97316" },
    { "min": 20, "max": 27, "label": "Severe Depression", "severity": "critical", "color": "#ef4444" }
  ]
}

7. Demographic Standardization Norms (norms)

Enables offline transformation of raw score aggregates into standardized population metrics (T-Scores, Percentile Ranks, Stanine, and Z-Scores).

"norms": [
  {
    "name": "General Population Sample (18-65)",
    "sample_size": 2500,
    "table": [
      { "raw_score": 0, "percentile": 50.0, "t_score": 50, "stanine": 5 },
      { "raw_score": 10, "percentile": 84.1, "t_score": 60, "stanine": 7 },
      { "raw_score": 20, "percentile": 97.7, "t_score": 70, "stanine": 9 }
    ]
  }
]

8. Canonical Implementation: PHQ-9

Complete, verified reference document of the Patient Health Questionnaire-9:

{
  "$schema": "https://fidetest.de/ptf.schema.json",
  "meta": {
    "name": "Patient Health Questionnaire-9",
    "abbreviation": "PHQ-9",
    "description": "Standardized depression severity screening tool based on DSM-5 criteria.",
    "version": "1.0.0",
    "schema_version": "2.0.0",
    "language": "en",
    "authors": [
      { "name": "Kurt Kroenke", "affiliation": "Indiana University School of Medicine" },
      { "name": "Robert L. Spitzer", "affiliation": "Columbia University" }
    ],
    "citation": "Kroenke, K. et al. (2001). The PHQ-9. J Gen Intern Med, 16(9), 606-613.",
    "license": { "type": "open-access", "notice": "Public Domain (Pfizer Open Instrument)" },
    "target_audience": "Adults and Adolescents (12+)",
    "duration_minutes": 3,
    "rater": "self",
    "tags": ["Depression", "Screening", "Outcome Measurement"]
  },
  "items": [
    {
      "id": "phq_1",
      "type": "radio",
      "text": "1. Little interest or pleasure in doing things",
      "required": true,
      "options": [
        { "label": "Not at all", "score": 0 },
        { "label": "Several days", "score": 1 },
        { "label": "More than half the days", "score": 2 },
        { "label": "Nearly every day", "score": 3 }
      ]
    },
    {
      "id": "phq_2",
      "type": "radio",
      "text": "2. Feeling down, depressed, or hopeless",
      "required": true,
      "options": [
        { "label": "Not at all", "score": 0 },
        { "label": "Several days", "score": 1 },
        { "label": "More than half the days", "score": 2 },
        { "label": "Nearly every day", "score": 3 }
      ]
    }
  ],
  "scoring": {
    "type": "sum",
    "min_score": 0,
    "max_score": 27,
    "cutoffs": [
      { "min": 0, "max": 4, "label": "None / Minimal", "severity": "none", "color": "#10b981" },
      { "min": 5, "max": 9, "label": "Mild Depression", "severity": "mild", "color": "#3b82f6" },
      { "min": 10, "max": 14, "label": "Moderate Depression", "severity": "moderate", "color": "#f59e0b" },
      { "min": 15, "max": 19, "label": "Moderately Severe Depression", "severity": "severe", "color": "#f97316" },
      { "min": 20, "max": 27, "label": "Severe Depression", "severity": "critical", "color": "#ef4444" }
    ]
  }
}

9. Machine-Readable Schema Distribution

The formal JSON Schema Draft-07 specification is hosted globally on Cloudflare Edge CDN:

10. TypeScript & Go Interface Definitions

export interface PTFDocument {
  $schema?: string;
  meta: {
    name: string;
    abbreviation?: string;
    description?: string;
    version?: string;
    schema_version: string;
    language: string;
    authors?: Array<{ name: string; affiliation?: string; orcid?: string }>;
    rater?: 'self' | 'clinician' | 'caregiver' | 'teacher' | 'observer';
    tags?: string[];
  };
  items: Array<{
    id: string;
    type: 'radio' | 'scale' | 'slider' | 'checkbox' | 'multiselect' | 'text' | 'info';
    text: string;
    required?: boolean;
    options?: Array<{ label: string; score: number; value?: any }>;
    subscale?: string;
    no_score?: boolean;
  }>;
  scoring?: {
    type: 'sum' | 'mean' | 'custom';
    min_score?: number;
    max_score?: number;
    subscales?: Array<{ id: string; name: string; items: string[] }>;
    cutoffs?: Array<{ min: number; max: number; label: string; severity?: string; color?: string }>;
  };
}

11. LLM Ingestion & Automated Parser Protocol

Prompt protocol for large language models (Gemini, Claude, GPT-4) to parse unstructured test questionnaires directly into conforming PTF v2.0 JSON:

12. Citation & References

To cite this standard in academic publications, clinical software specifications, or clinical trials:

@standard{gawron2026ptf,
  author    = {Gawron, Martin Edward},
  title     = {The Psychological Test Format (.ptf): A Standardized JSON Schema for Machine-Readable Clinical Diagnostics and Interoperable Research Data},
  version   = {2.0.0},
  year      = {2026},
  publisher = {Fidetest Open Standards},
  url       = {https://fidetest.de/ptf},
  note      = {Canonical JSON Schema: https://fidetest.de/ptf.schema.json}
}