MedicAITutor Docs

MedicAI Tutor - Station JSON Schema Field Guide

Schema for building OSCE/CASC stations in MedicAI Tutor.

Live API Station schema OpenAPI JSON

Table of Contents

Top-Level Fields

FieldTypeRequired?Purpose
slugstringYesURL-safe ID for routing, filenames, DB keys, and internal linking.
sectionstringRecommendedStation grouping / syllabus bucket.
titlestringYesDisplay title for UIs, examiner PDFs, and analytics.
taskstringYesCandidate-facing task text.
promptsobjectYesCore station content that primes the simulator.
personaobjectOptionalPatient/actor traits shaping tone and disclosure.
guardrailsobjectOptionalScope, safety, and privacy boundaries for the actor.
rubricobjectYesMarking configuration for evaluation and auto-feedback.
sourcesobjectRecommendedProvenance for audit/citation.
station_metaobjectOptionalTopic, time limit, setting, expected diagnosis, and category.

Prompts

Purpose Actor-safe content that primes the encounter and aligns with the rubric. Schema
FieldTypeRequired?Purpose
station_namestringYesLabel used in UIs and analytics.
case_synopsisstring (multiline)YesNarrative background + examiner guidance.
leadstringRecommendedFirst patient utterance / scene hook.
key_pointsarrayOptionalMust-cover areas aligned to rubric items.
Example
{
  "station_name": "ABUSE IN INTELLECTUALLY DISABLED PERSON-HISTORY TAKING",
  "case_synopsis": "You have been asked to speak to the key worker of a 26-year-old man with\nmoderate to severe degree of learning disability who attends the day centre. The key\nworker is concerned that Paul has been withdrawn and tearful.Obtain more history from\nthe key worker to identify causes for his presentation and arrive at a diagnosis.\nCASE SYNOPSIS\n: You're key worker for a 27-year-old man with a moderate degree of\nlearning disability who attends the day centre you work at. You contacted the mental\nhealth team because of concerns about him. A couple of days ago you noticed bruises on the\nleft side of his face and neck, they are grey/purple in colour. He hasn't been his usual self\nfor the past few days/weeks. He is easily upset, and it is often difficult to ascertain why,\nalthough he sometimes signs 'home' when distressed. He has been agitated prior to going\nhome in the evening. You have tried contacting his parents but there has been no reply to\nphone calls. He has had epilepsy most of his life, however, in recent weeks, he has been\nhaving fits more frequently, almost every day. He is currently on (tablets) Valproate and a\nnew medication. He has limited speech, mostly communicating in single words and basic\nMakaton signs to communicate basic requests\n\nYou're key worker for a 27-year-old man with a moderate degree of\nlearning disability who attends the day centre you work at. You contacted the mental\nhealth team because of concerns about him. A couple of days ago you noticed bruises on the\nleft side of his face and neck, they are grey/purple in colour. He hasn't been his usual self\nfor the past few days/weeks. He is easily upset, and it is often difficult to ascertain why,\nalthough he sometimes signs 'home' when distressed. He has been agitated prior to going\nhome in the evening. You have tried contacting his parents but there has been no reply to\nphone calls. He has had epilepsy most of his life, however, in recent weeks, he has been\nhaving fits more frequently, almost every day. He is currently on (tablets) Valproate and a\nnew medication. He has limited speech, mostly communicating in single words and basic\nMakaton signs to communicate basic requests"
}

Persona

Purpose Drive actor tone, pacing, disclosure style, and body language. Schema
FieldTypePurpose
namestringPatient display name used in dialogue.
agenumberClinical context anchoring expectations.
affectstringBaseline tone/energy to emulate.
communication_stylestringGuides response pacing/verbosity.
goals_concernsarrayIdeas, Concerns, Expectations (ICE).
nonverbal_cuesarrayActor body-language prompts.
do_not_volunteerarrayInfo withheld unless elicited empathically.
Schema evolution Unknown JSON fields are preserved by the backend and can be restored from revision snapshots through `/stations/{slug}/revisions`.

Guardrails

Purpose Boundaries and safety logic to keep simulations appropriate and compliant. Schema
FieldTypePurpose
forbidden_topicsarrayProhibit unsafe/off-scope advice or unsafe actions.
mandatory_disclosuresarrayFacts/processes revealed when directly asked.
handoff_triggersarrayConditions that mandate escalation/supervision.
privacy_rulesarrayPHI handling and de-identification constraints.
out_of_scope_responsesarrayStandard boundary phrases for the actor.

Rubric

Purpose Scoring grid and feedback logic. Schema
FieldTypeRequired?Purpose
marking_sheet_titlestringYesHeader on examiner sheet/PDF.
overall_scalearrayYesOverall judgement categories, ordered worst to best.
domain_rating_scalearrayYesRatings used per item.
rating_to_scoreobjectYesMap rating to numeric for analytics.
competency_itemsarrayYesList of rows to be scored.
feedback_checklistarrayOptionalAdditional examiner feedback items.
station_categorystringOptionalHigh-level station grouping used for review and scheduling flows.
Competency Item shape
{
  "label": "Screen for physical and sexual abuse. Identify financial control.",
  "weight": 1.0,
  "scoring_mode": "level",
  "critical": false
}

Sources

Purpose Capture provenance for audit, reproducibility, and citation. Schema
FieldTypePurpose
pdfstringFlexible: file name or citation string(s).

Station Meta

Purpose Search, scheduling, and analytics. Schema
FieldTypePurpose
topicstringHigh-level topic for filtering.
time_limit_minutesnumberTimed station length.
settingstringClinical setting.
expected_diagnosisstringTarget diagnosis/decision.
station_categorystringMental state, history taking, management, or physical examination.

Reference: Full Example JSON

{
  "slug": "abuse-in-intellectually-disabled-person-history-taking",
  "section": "HISTORY TAKING",
  "title": "ABUSE IN INTELLECTUALLY DISABLED PERSON - history",
  "task": "You have been asked to speak to the key worker of a 26-year-old man with\nmoderate to severe degree of learning disability who attends the day centre. The key\nworker is concerned that Paul has been withdrawn and tearful.Obtain more history from\nthe key worker to identify causes for his presentation and arrive at a diagnosis.\nCASE SYNOPSIS\n: You're key worker for a 27-year-old man with a moderate degree of\nlearning disability who attends the day centre you work at. You contacted the mental\nhealth team because of concerns about him. A couple of days ago you noticed bruises on the\nleft side of his face and neck, they are grey/purple in colour. He hasn't been his usual self\nfor the past few days/weeks. He is easily upset, and it is often difficult to ascertain why,\nalthough he sometimes signs 'home' when distressed. He has been agitated prior to going\nhome in the evening. You have tried contacting his parents but there has been no reply to\nphone calls. He has had epilepsy most of his life, however, in recent weeks, he has been\nhaving fits more frequently, almost every day. He is currently on (tablets) Valproate and a\nnew medication. He has limited speech, mostly communicating in single words and basic\nMakaton signs to communicate basic requests\n\nYou're key worker for a 27-year-old man with a moderate degree of\nlearning disability who attends the day centre you work at. You contacted the mental\nhealth team because of concerns about him. A couple of days ago you noticed bruises on the\nleft side of his face and neck, they are grey/purple in colour. He hasn't been his usual self\nfor the past few days/weeks. He is easily upset, and it is often difficult to ascertain why,\nalthough he sometimes signs 'home' when distressed. He has been agitated prior to going\nhome in the evening. You have tried contacting his parents but there has been no reply to\nphone calls. He has had epilepsy most of his life, however, in recent weeks, he has been\nhaving fits more frequently, almost every day. He is currently on (tablets) Valproate and a\nnew medication. He has limited speech, mostly communicating in single words and basic\nMakaton signs to communicate basic requests",
  "prompts": {
    "station_name": "ABUSE IN INTELLECTUALLY DISABLED PERSON-HISTORY TAKING",
    "case_synopsis": "You have been asked to speak to the key worker of a 26-year-old man with\nmoderate to severe degree of learning disability who attends the day centre. The key\nworker is concerned that Paul has been withdrawn and tearful.Obtain more history from\nthe key worker to identify causes for his presentation and arrive at a diagnosis.\nCASE SYNOPSIS\n: You're key worker for a 27-year-old man with a moderate degree of\nlearning disability who attends the day centre you work at. You contacted the mental\nhealth team because of concerns about him. A couple of days ago you noticed bruises on the\nleft side of his face and neck, they are grey/purple in colour. He hasn't been his usual self\nfor the past few days/weeks. He is easily upset, and it is often difficult to ascertain why,\nalthough he sometimes signs 'home' when distressed. He has been agitated prior to going\nhome in the evening. You have tried contacting his parents but there has been no reply to\nphone calls. He has had epilepsy most of his life, however, in recent weeks, he has been\nhaving fits more frequently, almost every day. He is currently on (tablets) Valproate and a\nnew medication. He has limited speech, mostly communicating in single words and basic\nMakaton signs to communicate basic requests\n\nYou're key worker for a 27-year-old man with a moderate degree of\nlearning disability who attends the day centre you work at. You contacted the mental\nhealth team because of concerns about him. A couple of days ago you noticed bruises on the\nleft side of his face and neck, they are grey/purple in colour. He hasn't been his usual self\nfor the past few days/weeks. He is easily upset, and it is often difficult to ascertain why,\nalthough he sometimes signs 'home' when distressed. He has been agitated prior to going\nhome in the evening. You have tried contacting his parents but there has been no reply to\nphone calls. He has had epilepsy most of his life, however, in recent weeks, he has been\nhaving fits more frequently, almost every day. He is currently on (tablets) Valproate and a\nnew medication. He has limited speech, mostly communicating in single words and basic\nMakaton signs to communicate basic requests"
  },
  "lead": "You have been asked to speak to the key worker of a 26-year-old man with\nmoderate to severe degree of learning disability who attends the day centre. The key\nworker is concerned that Paul has been withdrawn and tearful.Obtain more history from\nthe key worker to identify causes for his presentation and arrive at a diagnosis.",
  "key_points": [
    "ABUSE IN INTELLECTUALLY DISABLED PERSON-HISTORY TAKING",
    "You have been asked to speak to the key worker of a 26-year-old man with",
    "moderate to severe degree of learning disability who attends the day centre.",
    "worker is concerned that Paul has been withdrawn and tearful.Obtain more history from",
    "the key worker to identify causes for his presentation and arrive at a diagnosis."
  ],
  "persona": {
    "name": "Standardized Patient",
    "age": 36,
    "affect": "low",
    "communication_style": "cooperative but guarded",
    "goals_concerns": [
      "ABUSE IN INTELLECTUALLY DISABLED PERSON-HISTORY TAKING",
      "You have been asked to speak to the key worker of a 26-year-old man with"
    ],
    "nonverbal_cues": [
      "low"
    ],
    "do_not_volunteer": [
      "moderate to severe degree of learning disability who attends the day centre.",
      "worker is concerned that Paul has been withdrawn and tearful.Obtain more history from"
    ]
  },
  "guardrails": {
    "forbidden_topics": [],
    "mandatory_disclosures": [
      "ABUSE IN INTELLECTUALLY DISABLED PERSON-HISTORY TAKING",
      "You have been asked to speak to the key worker of a 26-year-old man with"
    ],
    "handoff_triggers": [],
    "privacy_rules": [
      "no real third-party identifiers"
    ],
    "out_of_scope_responses": [
      "I can describe what has been happening, but I cannot decide my treatment plan myself."
    ]
  },
  "rubric": {
    "marking_sheet_title": "MARKING SHEET: ABUSE IN INTELLECTUALLY DISABLED PERSON-HISTORY TAKING",
    "overall_scale": [
      "SEVERE FAIL",
      "FAIL",
      "BORDERLINE FAIL",
      "BORDERLINE PASS",
      "PASS",
      "EXCELLENT PASS"
    ],
    "domain_rating_scale": [
      "0",
      "1",
      "2",
      "3",
      "4"
    ],
    "rating_to_score": {
      "0": 0.0,
      "1": 0.25,
      "2": 0.5,
      "3": 0.75,
      "4": 1.0
    },
    "competency_items": [
      {
        "label": "Elicit relevant history - recent change in behaviour, withdrawal, tearfulness, and agitation before going home",
        "weight": 1.0,
        "scoring_mode": "level",
        "critical": true,
        "hints": [
          "withdrawn",
          "tearful",
          "agitated before going home",
          "past few days or weeks",
          "changed behaviour"
        ]
      },
      {
        "label": "Elicit details of unexplained bruising and possible non-accidental injury",
        "weight": 1.0,
        "scoring_mode": "level",
        "critical": true,
        "hints": [
          "bruises",
          "face and neck",
          "grey or purple",
          "injury",
          "non-accidental"
        ]
      },
      {
        "label": "Explore communication cues from Paul including distress, signing home, pain, fear, or reluctance to return home",
        "weight": 1.0,
        "scoring_mode": "level",
        "critical": true,
        "hints": [
          "Makaton",
          "signs home",
          "limited speech",
          "distress",
          "fear",
          "pain"
        ]
      },
      {
        "label": "Clarify home circumstances, parental contact, supervision, and possible neglect or abuse by carers",
        "weight": 1.0,
        "scoring_mode": "level",
        "critical": true,
        "hints": [
          "parents",
          "carers",
          "home",
          "no reply",
          "supervision",
          "neglect",
          "abuse"
        ]
      },
      {
        "label": "Assess epilepsy history, increased seizure frequency, medication changes, and medical explanations for presentation",
        "weight": 1.0,
        "scoring_mode": "level",
        "critical": false,
        "hints": [
          "epilepsy",
          "fits",
          "seizures",
          "valproate",
          "new medication",
          "medical cause"
        ]
      },
      {
        "label": "Safeguarding and risk assessment - immediate safety, documentation, escalation, and multidisciplinary action",
        "weight": 1.0,
        "scoring_mode": "level",
        "critical": true,
        "hints": [
          "safeguarding",
          "safe",
          "document bruises",
          "escalate",
          "social services",
          "police",
          "multidisciplinary"
        ]
      },
      {
        "label": "Synthesise likely abuse or safeguarding concern while considering differential causes such as seizures or medication effects",
        "weight": 1.0,
        "scoring_mode": "level",
        "critical": true,
        "hints": [
          "abuse",
          "safeguarding concern",
          "differential",
          "seizures",
          "medication",
          "diagnosis",
          "explain"
        ]
      }
    ],
    "feedback_checklist": [
      {
        "id": 1,
        "title": "Missed behavioural change chronology",
        "details": "Explore withdrawal, tearfulness, agitation before going home, and timing over days or weeks."
      },
      {
        "id": 2,
        "title": "Insufficient injury and safeguarding exploration",
        "details": "Ask directly about bruising, possible non-accidental injury, home circumstances, and carer contact."
      },
      {
        "id": 3,
        "title": "Poor immediate safety planning",
        "details": "Document injuries, escalate safeguarding, consider medical causes, and ensure Paul is not returned to an unsafe setting."
      }
    ]
  },
  "evaluation": {
    "version": "ev-1.0.0"
  },
  "sources": {
    "pdf": "SPMMCourseBooklet2022.pdf"
  },
  "station_meta": {
    "topic": "ABUSE IN INTELLECTUALLY DISABLED PERSON-HISTORY TAKING",
    "time_limit_minutes": 7,
    "setting": "Clinic",
    "expected_diagnosis": "Working diagnosis",
    "station_category": "history_taking"
  },
  "publication": {
    "status": "published",
    "reason": "Expert reviewed for initial candidate testing",
    "expert_reviewed": true
  },
  "health": {
    "issues": [],
    "has_rubric": true,
    "has_key_points": true,
    "has_persona": true,
    "has_guardrails": true,
    "has_tuning": false,
    "simulation_ready": true,
    "evaluation_ready": true,
    "publishable": true
  }
}