Skip to documentation
.usim
ReferenceStart here

Start here

Getting started

Follow one scenario from its first definition to a learning experience.

Begin with the five scenario domains: metadata, patients, environment, education, and events. Write the educational objective first, describe the starting patient and setting, then connect a baseline to one or more conclusions through meaningful decisions.

The complete example below uses the canonical scenario schema. It includes patient history, a clinical snapshot, actors, a reusable result, two decision paths, and a scheduled update. The same document can be authored, validated, stored and exported.

  1. 01

    Define the learning

    Describe the objective, prerequisites, audience, and debrief before adding events.

  2. 02

    Describe the starting point

    Add fictional patient context, history, examination, vital signs, and scenario requirements.

  3. 03

    Connect decisions and time

    Create states, connect actions, and declare delayed content or scheduled edges explicitly.

  4. 04

    Validate and use the scenario

    Open Builder to author and validate. Publish a fixed revision, generate role outputs, and run that revision in Campus.

Open Builder Read the profile

A complete scenario

Execution capabilities · Fictional authored example

scenario-example.jsonJSON
{
  "format": "usim-scenario",
  "formatVersion": "2.0",
  "scenarioId": "usim-reference-1",
  "metadata": {
    "revision": 1,
    "license": {
      "identifier": "All rights reserved"
    },
    "review": {
      "status": "draft",
      "reviewerIds": [],
      "sourceIds": []
    },
    "sources": [],
    "title": "A clear handoff",
    "summary": "Fictional team communication practice with a delayed result and two approaches to clarifying the situation.",
    "contributors": [
      {
        "id": "contributor-author",
        "roles": [
          "author"
        ],
        "name": "u-sim example team"
      }
    ],
    "diagnosis": "Communication rehearsal",
    "specialty": "Simulation education",
    "level": "Intermediate",
    "durationMinutes": 10
  },
  "patients": [
    {
      "id": "patient-primary",
      "name": "Alex Morgan (fictional)",
      "context": "A fictional adult is awaiting handoff. The incoming team needs a shared understanding of the situation and who will follow up an outstanding result.",
      "demographics": {
        "age": {
          "value": 40,
          "unit": "years"
        },
        "gender": "Not specified",
        "weight": {
          "value": 70,
          "unit": "kg"
        },
        "height": {
          "value": 170,
          "unit": "cm"
        }
      },
      "monitor": {
        "connections": {}
      },
      "variables": [
        {
          "id": "patient-primary-hr",
          "concept": "usim:hr",
          "value": 80,
          "unit": "beats/min"
        },
        {
          "id": "patient-primary-sbp",
          "concept": "usim:sbp",
          "value": 120,
          "unit": "mmHg"
        },
        {
          "id": "patient-primary-dbp",
          "concept": "usim:dbp",
          "value": 75,
          "unit": "mmHg"
        },
        {
          "id": "patient-primary-rr",
          "concept": "usim:rr",
          "value": 16,
          "unit": "breaths/min"
        },
        {
          "id": "patient-primary-spo2",
          "concept": "usim:spo2",
          "value": 98,
          "unit": "%"
        },
        {
          "id": "patient-primary-temperature",
          "concept": "usim:temperature",
          "value": 37,
          "unit": "Cel"
        },
        {
          "id": "patient-primary-etco2",
          "concept": "usim:etco2",
          "value": 35,
          "unit": "mmHg"
        }
      ],
      "history": [
        {
          "id": "patient-primary-history-chief-complaint-1",
          "content": "Awaiting a team handoff",
          "disclosure": {
            "audience": [
              "learner",
              "facilitator"
            ],
            "mode": "initial"
          },
          "category": "chief-complaint"
        },
        {
          "id": "patient-primary-history-present-illness-1",
          "content": "The current care summary is incomplete in this fictional exercise.",
          "disclosure": {
            "audience": [
              "learner",
              "facilitator"
            ],
            "mode": "initial"
          },
          "category": "present-illness"
        },
        {
          "id": "patient-primary-history-medical-1",
          "content": "No additional history authored",
          "disclosure": {
            "audience": [
              "learner",
              "facilitator"
            ],
            "mode": "initial"
          },
          "category": "medical"
        },
        {
          "id": "patient-primary-history-allergy-1",
          "content": "Example substance — Reaction: Authored rash — Reaction severity: mild",
          "disclosure": {
            "audience": [
              "learner",
              "facilitator"
            ],
            "mode": "initial"
          },
          "category": "allergy",
          "allergy": {
            "substance": "Example substance",
            "reaction": "Authored rash",
            "severity": "mild"
          }
        },
        {
          "id": "patient-primary-history-family-1",
          "content": "Not part of this exercise",
          "disclosure": {
            "audience": [
              "learner",
              "facilitator"
            ],
            "mode": "initial"
          },
          "category": "family"
        },
        {
          "id": "patient-primary-history-social-1",
          "content": "Fictional training context",
          "disclosure": {
            "audience": [
              "learner",
              "facilitator"
            ],
            "mode": "initial"
          },
          "category": "social"
        }
      ]
    }
  ],
  "environment": {
    "setting": "A simulated handoff space",
    "requirements": [
      {
        "id": "requirement-1",
        "description": "Facilitator brief reviewed"
      },
      {
        "id": "requirement-2",
        "description": "Learner roles assigned"
      }
    ],
    "equipment": [
      "Handoff note"
    ],
    "actors": [
      {
        "id": "outgoing-team",
        "name": "Outgoing colleague",
        "role": "Facilitator",
        "brief": "Reveal missing context when the learner asks a focused question."
      }
    ]
  },
  "education": {
    "objectives": [
      {
        "id": "objective-1",
        "statement": "Clarify missing information"
      },
      {
        "id": "objective-2",
        "statement": "Agree on ownership of the next step"
      }
    ],
    "debriefPrompts": [
      {
        "id": "debrief-1",
        "question": "How did you establish a shared understanding? Who took responsibility for the outstanding result?"
      }
    ],
    "preparation": [
      {
        "id": "preparation-handoff",
        "audience": "learner",
        "instructions": "Familiarity with a local handoff framework",
        "assetIds": []
      }
    ],
    "rationale": "Practice explicit communication and follow-up ownership."
  },
  "events": {
    "states": [
      {
        "id": "baseline",
        "title": "Receive the handoff",
        "kind": "baseline",
        "key": true,
        "learnerBrief": "The outgoing colleague is ready. How will you establish the shared picture?",
        "facilitatorBrief": "Offer incomplete context, then respond to the learner’s approach."
      },
      {
        "id": "assessment",
        "title": "Clarify the context",
        "kind": "phase",
        "key": true,
        "learnerBrief": "You have clarified the missing information. Agree on the next step.",
        "facilitatorBrief": "Ask the learner to make ownership explicit."
      },
      {
        "id": "waiting",
        "title": "Await the update",
        "kind": "phase",
        "learnerBrief": "A result is pending. Agree who will review it while the simulated clock advances.",
        "facilitatorBrief": "Advance simulated time to allow the update."
      },
      {
        "id": "update",
        "title": "The update arrives",
        "kind": "phase",
        "learnerBrief": "The pending update is available. Confirm who will communicate the result.",
        "facilitatorBrief": "Ask for a closed-loop confirmation.",
        "onEnterEffectIds": [
          "update-hr"
        ]
      },
      {
        "id": "conclusion",
        "title": "Handoff complete",
        "kind": "conclusion",
        "key": true,
        "learnerBrief": "The team has confirmed the situation and the next step. Pause for reflection.",
        "facilitatorBrief": "Use the debrief prompts to compare both approaches."
      }
    ],
    "effects": [
      {
        "id": "update-hr",
        "targetId": "patient-primary-hr",
        "value": 82,
        "unit": "beats/min",
        "kind": "set-variable"
      }
    ],
    "actions": [
      {
        "id": "clarify",
        "label": "Ask for missing context",
        "availableInStateIds": [
          "baseline"
        ],
        "outcomes": [
          {
            "id": "clarify-outcome",
            "effectIds": [],
            "nextStateId": "assessment"
          }
        ]
      },
      {
        "id": "review",
        "label": "Review the summary and pending result",
        "availableInStateIds": [
          "baseline"
        ],
        "outcomes": [
          {
            "id": "review-outcome",
            "effectIds": [],
            "nextStateId": "waiting"
          }
        ],
        "resourceId": "handoff-result"
      },
      {
        "id": "confirm",
        "label": "Confirm responsibilities with a read-back",
        "availableInStateIds": [
          "assessment"
        ],
        "outcomes": [
          {
            "id": "confirm-outcome",
            "effectIds": [],
            "nextStateId": "conclusion"
          }
        ]
      },
      {
        "id": "close",
        "label": "Confirm who will communicate the result",
        "availableInStateIds": [
          "update"
        ],
        "outcomes": [
          {
            "id": "close-outcome",
            "effectIds": [],
            "nextStateId": "conclusion"
          }
        ]
      }
    ],
    "schedules": [
      {
        "id": "update-due",
        "label": "Receive the scheduled update",
        "anchor": {
          "kind": "state-entry",
          "refId": "waiting"
        },
        "delaySeconds": 30,
        "priority": 0,
        "effectIds": [],
        "nextStateId": "update",
        "onAnchorStateExit": "continue"
      }
    ]
  },
  "resources": [
    {
      "id": "handoff-result",
      "kind": "information",
      "name": "Pending handoff update",
      "description": "A fictional delayed update used to rehearse follow-up ownership.",
      "source": "Authored fictional documentation example",
      "results": [
        {
          "id": "handoff-result-result",
          "content": "The requested handoff information is now available. Confirm that the incoming colleague has received it.",
          "observationIds": [],
          "assetIds": [],
          "disclosure": {
            "audience": [
              "learner",
              "facilitator"
            ],
            "mode": "on-resource-response",
            "resourceId": "handoff-result"
          }
        }
      ],
      "response": {
        "delaySeconds": 30
      }
    }
  ],
  "observations": [
    {
      "id": "patient-primary-examination-general",
      "patientId": "patient-primary",
      "code": "usim:examination:general",
      "kind": "finding",
      "disclosure": {
        "audience": [
          "learner",
          "facilitator"
        ],
        "mode": "initial"
      },
      "status": "known",
      "value": "Comfortable and speaking with the team"
    },
    {
      "id": "patient-primary-ros-general",
      "patientId": "patient-primary",
      "code": "usim:ros:general",
      "kind": "symptom",
      "disclosure": {
        "audience": [
          "learner",
          "facilitator"
        ],
        "mode": "initial"
      },
      "status": "known",
      "value": "No additional symptoms authored"
    }
  ]
}

This is a raw scenario object. Package envelopes add publication and format metadata around it. The structural schema does not replace reference, timing, or publication validation.

Field catalog551 field definitionsComplete exampleFictional .usim documentProfile schemaStructural JSON Schema · application scope
Compatibility and current support