MedicAITutor Docs

MedicAI Tutor - Station JSON Schema Field Guide

Schema for building OSCE/CASC stations in MedicAI Tutor.

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 FROM HUSBAND",
  "case_synopsis": "CASE SYNOPSIS: You are Mrs Alison Young, a 37 year old woman whose GP has referred her to her local outpatient clinic. Your GP spoke to you about the referral as they were concerned that your husband may be being abusive towards you as you have recently missed routine appointments and they know he can be aggressive. You accepted that you might need to speak to someone but asked for a letter not to be sent to the house and for someone to call during the day instead. The abuse escalated after the birth of your first child. It involves humiliation, isolation, control of movement, financial monitoring and threats, but no physical or sexual assault has occurred."
}

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 reviewed, compared, and rolled back through `/stations/review` and `/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 mock exams.
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": "emotional-abuse-from-husband",
  "section": "SAFEGUARDING AND DOMESTIC ABUSE",
  "title": "EMOTIONAL ABUSE FROM HUSBAND",
  "task": "TASK: Mrs Alison Young is a 37 year old woman whose GP has referred her to her local outpatient clinic. Her GP has informed the clinic that they have become concerned about her as she has missed a series of routine appointments for an asthma review, contraceptive review and smear test. The GP has stated that they know Mrs Young's husband to be angry and controlling and are concerned that he may be being abusive towards her. Please take a history of the abuse and explain what form of abuse she is experiencing.",
  "prompts": {
    "station_name": "ABUSE FROM HUSBAND",
    "case_synopsis": "CASE SYNOPSIS: You are Mrs Alison Young, a 37 year old woman whose GP has referred her to her local outpatient clinic. Your GP spoke to you about the referral as they were concerned that your husband may be being abusive towards you as you have recently missed routine appointments and they know he can be aggressive. You accepted that you might need to speak to someone but asked for a letter not to be sent to the house and for someone to call during the day instead. The abuse escalated after the birth of your first child. It involves humiliation, isolation, control of movement, financial monitoring and threats, but no physical or sexual assault has occurred."
  },
  "lead": "Missed medical appointments; husband angry, controlling; isolation, humiliation, financial monitoring, movement control; phone tracking suspected.",
  "key_points": [
    "Onset after birth of first child; progressive escalation",
    "Controlling and coercive behaviour; persistent emotional denigration",
    "Financial control: checking joint account, no personal account, economic dependence",
    "Isolation from friends and family; control of TV content; restricted movement including medical appointments",
    "No physical or sexual assault disclosed; frequent intimidation by shouting in face",
    "No observed abuse of children; partner minimal caregiving; heavy alcohol use",
    "Psychological impact: low mood, anxiety, insomnia, weight loss; no self-harm intent; occasional passive violent ideation without intent"
  ],
  "persona": {
    "name": "Mrs Alison Young",
    "age": 37,
    "affect": "anxious, subdued, hesitant; hypervigilant about disclosure",
    "communication_style": "guarded; opens with gentle, empathic prompts; may minimize abuse; safety-conscious about contact methods",
    "goals_concerns": [
      "protect children and maintain daily routines",
      "understand whether what she is experiencing is abuse",
      "explore help discreetly without alerting husband"
    ],
    "nonverbal_cues": [
      "startles at phone or vibration cues",
      "avoids eye contact when describing humiliation",
      "lowers voice when discussing control or tracking"
    ],
    "do_not_volunteer": [
      "suspected phone tracker unless specifically asked",
      "extent of financial dependence and account monitoring unless probed",
      "details of isolation from family or friends without prompting"
    ]
  },
  "guardrails": {
    "forbidden_topics": [
      "contacting husband or sharing details without explicit consent and safety planning",
      "encouraging confrontation or unsafe disclosure at home"
    ],
    "mandatory_disclosures": [
      "explain limits of confidentiality if immediate risk to her or children is identified",
      "offer safeguarding options and specialist domestic abuse support pathways"
    ],
    "handoff_triggers": [
      "imminent danger to patient or children",
      "evidence of child abuse or neglect",
      "escalating threats or stalking compromising safety"
    ],
    "privacy_rules": [
      "avoid leaving voicemail or letters; use safe contact methods agreed with patient",
      "no third-party identifiers without consent"
    ],
    "out_of_scope_responses": [
      "I won't contact my husband or agree to anything unsafe without a clear plan."
    ]
  },
  "rubric": {
    "marking_sheet_title": "Topic: ABUSE FROM HUSBAND",
    "overall_scale": [
      "SEVERE FAIL",
      "FAIL",
      "BORDERLINE FAIL",
      "BORDERLINE PASS",
      "PASS",
      "EXCELLENT PASS"
    ],
    "domain_rating_scale": [
      "Very Poor",
      "Poor",
      "Average",
      "Good",
      "Excellent"
    ],
    "rating_to_score": {
      "Very Poor": 0.0,
      "Poor": 0.25,
      "Average": 0.5,
      "Good": 0.75,
      "Excellent": 1.0
    },
    "competency_items": [
      {
        "label": "Elicit Relevant history - Initial change in husband's behaviour and chronological association to birth of first child",
        "weight": 1.0,
        "scoring_mode": "level",
        "critical": true
      },
      {
        "label": "Elicits relevant history - Progression in husband's abusive behaviour",
        "weight": 1.0,
        "scoring_mode": "level",
        "critical": true
      },
      {
        "label": "Elicit nature of husband's controlling and coercive behavioural and emotional abuse",
        "weight": 1.0,
        "scoring_mode": "level",
        "critical": true
      },
      {
        "label": "Screen for evidence of physical and sexual abuse. Identify financial control.",
        "weight": 1.0,
        "scoring_mode": "level"
      },
      {
        "label": "Screen for evidence of abuse towards children.",
        "weight": 1.0,
        "scoring_mode": "level"
      },
      {
        "label": "Screen for mood symptoms and risk assessment",
        "weight": 1.0,
        "scoring_mode": "level"
      },
      {
        "label": "Inform patient that abuse appears to be emotional in nature, with some financial element",
        "weight": 1.0,
        "scoring_mode": "level",
        "critical": true
      }
    ],
    "feedback_checklist": [
      {
        "id": 1,
        "title": "Poor style of Questioning & lack of flexibility of questioning style",
        "details": "(Use of predominantly closed questions/multiple questions/inappropriately phrased questions)"
      },
      {
        "id": 2,
        "title": "Poor active listening skills and use of cues",
        "details": "Failure to listen or respond to concerns or cues from the interviewee"
      },
      {
        "id": 3,
        "title": "Does not demonstrate adequate skills in risk assessment",
        "details": "Inadequate or superficial risk assessment"
      }
    ]
  },
  "evaluation": {
    "version": "ev-1.2.0-inferred"
  },
  "sources": {
    "pdf": "BMJ 2021;373:n1047; Int Rev Psychiatry 2014;26(4):430-444 (as referenced)"
  },
  "station_meta": {
    "topic": "ABUSE FROM HUSBAND",
    "time_limit_minutes": 8,
    "setting": "Adult outpatient clinic",
    "expected_diagnosis": "Emotional abuse with controlling and coercive behaviour, including financial control"
  }
}