RTSP — maschinenlesbare Fassung

Dieses Paket ist die maschinenlesbare Fassung des Rollenskript-Templates für Simulationspersonen (RTSP): TypeScript-Typen, Laufzeitschemata, die RTSP-Referenz, der Feldkatalog und die Zuordnung der Schemafelder zu den Parametern des Papiers.

Grundlage ist das RTSP-Papier, veröffentlicht als Open Educational Resource unter doi:10.3205/zma001812, Version 3.4. Gepflegt wird die Schema-Fassung an der Medizinischen Fakultät OWL der Universität Bielefeld.

Sie gilt für reale und für virtuelle Simulationspersonen. Ein Rollenskript gliedert sich in zwei Feldgruppen und ihre Bindung:

• Fall (RTSPCase): Datenblatt, Situation und Raum, Lehr- und Prüfinformationen, Hinweise an SP-Programm und Training — und je Rolle (RTSPRole) die Bedingungen an die Person, die Vorgeschichte, die Handlungsanweisung, das Reaktionsrepertoire und den inneren Monolog. Ein Fall kann eine oder mehrere Rollen umfassen. Kapitel 1 und 4 bis 13 des Papiers.
• Persona (RTSPPersona): Name, Alter, Geschlecht, Körper, Stimme, Persönlichkeit, Sprachen, Gesundheitskompetenz, Lebenssituation — was eine Simulationsperson mitbringt. Kapitel 2 und 3. Ein Fall verändert diese Angaben nicht; er stellt Bedingungen an sie, und das Casting prüft sie.
• Szenario (RTSPScenario): ein Fall mit gecasteten Rollen. Eine Bindung über Verweise auf Fall und Personas im selben Dokument.

Die Gruppen tragen die Kapitelnummern der veröffentlichten RTSP-Version 3.4. Ob ein Feld nur für reale (sp) oder nur für virtuelle (vsp) Simulationspersonen gilt, steht je Feld im Katalog. Die Herleitung des Schnitts und die Zuordnung jedes Elements des Papiers stehen im Repository virtualsp/virtualsp-webapp unter docs/fall-und-persona.md; die Entscheidung in docs/adr/0003-struktur-3-0-fall-und-persona.md hier.

Version 3.0 bricht mit 2.x. Bis 2.2.0 teilte sich ein Rollenskript in RTSPSituation und RTSPPersona, und die Persona trug den klinischen Fall. Dokumente nach 2.x sind mit 3.0 ungültig; die Umstellung ist eine Datenübernahme, keine Umbenennung. Das Vorgängerpaket @medfakowl/rtvsp-types bleibt installierbar und ist als veraltet markiert.

Installation

npm install @medfakowl/rtsp

Verwendung

import type { RTSPDocument, RTSPCase, RTSPPersona, RTSPScenario } from "@medfakowl/rtsp";

Ein Austauschdokument trägt Fälle, Personas und Szenarien getrennt; Szenarien verweisen auf Fälle und Personas im selben Dokument:

const dokument: RTSPDocument = {
  meta: { schemaVersion: "3.0.0", basedOnRtspVersion: "3.4" },
  cases: [fall],
  personas: [persona],
  scenarios: [{ id: "szenario-1", caseId: fall.meta.id, casting: [{ role: "Patientin", personaId: persona.meta.id }] }],
};

Laufzeitprüfung

Wer ein Dokument nicht nur typisieren, sondern prüfen will, bekommt die Schemata als Unterpfad. Zod ist dafür eine optionale Peer-Abhängigkeit; wer nur Typen braucht, merkt davon nichts.

import { documentSchema } from "@medfakowl/rtsp/zod";

const ergebnis = documentSchema.safeParse(unbekanntesDokument);

Die Schemata sind großzügig, wo der Standard großzügig ist — fast alles ist optional, weil ein Rollenskript nach und nach entsteht — und nicht abschließend: Unbekannte Felder einer neueren Version bleiben stehen, statt wegvalidiert zu werden. Pflicht ist, was das Papier als Pflicht führt, dazu das Wenige, ohne das eine Persona nicht castbar ist: Name, Alter, Geschlecht.

Versionierung

Die Version dieses Pakets folgt SemVer und ist von der Version des Papiers entkoppelt: Das wissenschaftliche Template ändert sich derzeit unabhängig von der Schema-Version. Welches Template ein Dokument abbildet, sagt meta.basedOnRtspVersion — heute "3.4". Paket 3.0.0 ist die maschinenlesbare Fassung von RTSP 3.4.

Datenartefakte

Das npm-Paket enthält fünf JSON-Dateien:

• data/rtsp_reference.json — die Kapitel und Parameter des Papiers, mit Nachträgen in meta.amendments
• data/rtsp_bindings.json — welches Schemafeld auf welchen Parameter des Papiers zurückgeht, für case und persona
• data/field_catalog.json — je Feld Pfad, Typ, Pflicht, erlaubte Werte samt Beschriftung, Beschriftung des Feldes (label), Hilfetext, Beispiele, Textform (line, prose), Einsatzform (both, sp, vsp) und Reifegrad. Gedacht für Redaktionsoberflächen und für Anwendungen, die Felder benennen müssen, ohne den Typ zu kennen
• data/field_history.json — die Geschichte des Feldkatalogs: je Version eine Zeile mit Datum, Nachricht und Zählung, und je Feld die Ereignisse, die es betreffen (added, changed, renamed, removed). Gedacht für Oberflächen, die an einem Feld zeigen wollen, seit wann es das gibt und was sich daran geändert hat
• data/proposals.json — Änderungsanträge an eine künftige Version des Papiers, mit Begründung aus der Arbeit an echten Fällen. Ein Antrag steht auf proposed, solange das Schema ihn nicht führt, auf in-schema, sobald er als Kandidat aufgenommen ist, und auf resolved, wenn die Struktur ihn ohne neues Feld erledigt hat

Katalog und Schemata werden erzeugt (npm run generate); npm run check meldet, wenn sie nicht mehr zu ihren Quellen passen.

Die Geschichte wird fortgeschrieben

data/field_history.json entsteht aus zwei Quellen (npm run history): den Katalogständen der Git-Tags und internal/history-notes.json. Der Vergleich zweier Stände sagt, welche Felder betroffen sind; die Notizdatei sagt, was geschehen ist — ein Vergleich allein liefert helpTextSource: docComment → editorial, und das ist keine Auskunft für einen Menschen.

Die Notizdatei trägt je Version einen Satz und ein Urteil. Das Urteil entscheidet, ob die Nachricht an die einzelnen Felder gehört (field) oder an den Katalog als Ganzes (catalog). Eine Version, die fast jedes Feld berührt, ist eine Nachricht über den Katalog: Der Sprung auf 3.1.0 hat alle 263 Felder verändert, weil die Redaktionsschicht dazukam — an jedem einzelnen stünde sie als Rauschen.

Wer das Paket hebt, trägt seine Version dort ein, bevor er veröffentlicht. npm run check meldet es, wenn der Feldkatalog vom letzten Tag abweicht und keine offene Version eingetragen ist — sonst ginge eine Veröffentlichung ohne ihre Geschichte hinaus, ohne dass es jemand merkt.

Zwei Quellen, ein Katalog

Der Feldkatalog entsteht aus zwei Dateien (ADR 0004):

| Quelle | Was sie sagt | | --- | --- | | index.d.ts | Die Struktur: welche Felder es gibt, Typ, Pflicht, erlaubte Werte, Einsatzform, Textform | | data/field_editorial.json | Die Texte: label, helpText und examples je Feld |

Am Feld steht außerdem helpTextSource — editorial, wenn der Hilfetext für diese Stelle geschrieben wurde, docComment, wenn er aus dem Kommentar der Typdatei stammt. Ohne diese Angabe sähen beide gleich aus, und eine Oberfläche könnte den Stand der Redaktion nicht zeigen. Die Legenden zu beiden Werten stehen im Katalog unter meta.helpTextSourceLegend.

Die Redaktionsdatei ist Quelle und wird nicht mitgeliefert; was sie trägt, steht im Katalog. Sie wächst Feld für Feld: Wo sie nichts sagt, ist label leer, examples leer, und helpText fällt auf den Doc-Kommentar der Typdatei zurück. Ein Eintrag zu einem Feld, das es nicht gibt, bricht den Lauf ab.

npm run redaktion zeigt, wie weit die Redaktion ist — je Feld, ob Beschriftung, Hilfetext und Beispiele gepflegt sind. Mit -- --voll stehen die Texte selbst dabei, mit einem Pfadstück als Argument nur die Felder darunter.

Die Textform sagt, ob ein Feld eine Zeile oder einen Text aufnimmt. line ist eine Angabe, die in eine Zeile passt — ein Bezeichner, ein Datum, eine Kennung. prose ist ausformulierter Text, der Raum braucht; auch ein einzelner langer Satz zählt dazu, etwa ein Lernziel in Operatorform. In der Typdatei steht sie als Marke @prose am Feld, neben @modality und @candidate. Gemeint ist der Inhalt, nicht das Bedienelement: Was eine Anwendung daraus macht, entscheidet sie selbst.

Auswahlwerte sind stabile englische Schlüssel ("teaching", "female", "human_medicine") mit deutschsprachiger Beschriftung. Sie steht im Katalog als enumLabels, dazu ein Satz je Wert als enumHelp; woher sie kommt, sagt enumLabelsSource — aus data/field_editorial.json (editorial) oder aus dem Zeilenkommentar hinter dem Union-Mitglied (typeComment). Die Konsistenzprüfung vergleicht die Beschriftungen mit der Referenz.

Werte auf einer Skala tragen am Feld ein scale mit Grenzen und der Beschriftung beider Pole — heute die fünf Dimensionen des Persönlichkeitsprofils. Das Dokument führt dort nur code und value; die Beschriftungen stehen im Katalog und nicht in jedem Dokument (ADR 0005).

Konsistenzprüfung

Hinweis: Die Konsistenzprüfung ist nur im Repo verfügbar und nicht Teil des veröffentlichten npm-Pakets.

npm run check

Der Check stellt sicher, dass Bindings, RTSP-Referenz und Typdefinitionen synchron bleiben, dass die erzeugten Artefakte aktuell sind, dass die Schemata sich an neun Fällen richtig verhalten (darunter ein echtes, anonymisiertes Dokument in internal/fixtures/) und dass die erzeugten Typdeklarationen selbst typprüfen.

Bewusste Abweichungen vom Papier

Jede Stelle, an der die Struktur vom Wortlaut des Papiers abweicht, mit dem Grund:

| Abweichung | Grund | | --- | --- | | Zwei Feldgruppen (Fall, Persona) statt eines Rollenskripts | Das Papier schreibt je Rolle ein Skript und setzt die Trennung von SP und Rolle voraus (Kapitel 9: „Die nachstehenden Ausführungen beziehen sich auf die SP selbst, nicht auf die dargestellte Rolle"); die Struktur macht sie explizit, damit Personas wiederverwendbar sind | | Rollen mit Bedingungen | Kapitel 4 kennt mehrere Akteure, Kapitel 1 das SP-Casting; die Struktur verbindet beides | | Kapitel 6.1 bis 6.4 je Rolle | Die Handlungsanweisung des Papiers gilt für eine SP; bei zwei Rollen sagt der Einstieg, wer spricht | | Gesundheitskompetenz an der Persona | Kapitel 5 führt sie unter Vorgeschichte, beschreibt sie aber als Fähigkeit der Person (Sørensen) | | Altersspanne als Bedingung, Alter als Zahl, Geburtstag ohne Jahr | Kapitel 2: Spanne im Skript, Geburtsdatum „in Abstimmung mit SP festgelegt" — die Struktur trennt die beiden Schritte | | Eine Struktur für alle Aussagen, mit Sprechmotivation und Auslöser, statt Prosa mit Spalte | Kapitel 5 hat die Spalte, Kapitel 6.3 beschreibt Haltungen mit Reaktion — die Struktur macht das entscheidbar | | Die zwei Grundregeln ohne Schalter | Das Papier stellt sie nicht zur Wahl | | Befunde als individualisierbare Vorlagen mit eingestuften Abschnitten | Kapitel 4 kennt Befundunterlagen als Dokumente; ein Befund braucht je Abschnitt eine Sprechmotivation, weil dort steht, wonach gefragt wird, und Name und Geburtsdatum kommen beim Casting aus der Persona | | Geschlechtsidentität und sexuelle Orientierung als zwei Felder | Kapitel 2 führt sie in einer Zeile; es sind zwei Fragen | | Lernziele als Katalog, Kennung, Beschreibung | Das Papier sagt „formuliert nach Fachtradition" und legt keinen Katalog fest | | Disziplinen: human_medicine (Humanmedizin) statt „Medizin", dazu other (Andere) | Humanmedizin ist präziser neben Zahn- und Tiermedizin; „Andere", weil die Einleitung des Papiers die Nutzung „über gesundheitliche Kontexte hinaus (Soziale Arbeit, Lehramt)" ausdrücklich zulässt | | Englische Schlüssel für Auswahlwerte | Das Papier liefert Beschriftungen, keine Schlüssel; die Beschriftungen stehen im Katalog | | Die Skalenbeschriftung des Persönlichkeitsprofils steht im Katalog, nicht im Dokument | Anhang 1 und 2 des Papiers legen die Pole fest; fünfzehn Konstanten in jedem Dokument könnten von ihnen abweichen | | RTSP.4.MehrereAkteure in der Referenz nachgetragen | Eine Tabellenzeile des Papiers, die in der Extraktion fehlte | | Profilbild, Stimme, KI-Konfiguration | Das Papier ist für Menschen geschrieben; die virtuelle Verkörperung ist der Grund für die maschinenlesbare Fassung |

Felder ohne Verankerung im Papier

Diese Felder gehören zum Schema, haben aber keine Entsprechung im RTSP-Papier. Sie sind optional; ein Dokument ohne sie bleibt gültig. Im Feldkatalog tragen sie den Reifegrad candidate. Jedes hat einen benannten Zweck:

• RTSPCase.shortDescription — Kurzbeschreibung für Listen und Kataloge auf Plattformen; steht am Fall und nicht im Datenblatt, weil das Papier sie nicht kennt
• RTSPCase.aiConfig.focusedVirtualSPCompetencies — ein bis zwei Kompetenzen aus dem VirtualSP-Kompetenzframework, auf die ein Training den Blick lenkt
• RTSPCase.aiConfig.channel — ob das Gespräch am Telefon (phone) oder vor Ort (inPerson) stattfindet
• RTSPCase.aiConfig.openedBy — wer das erste Wort hat, die Simulationsperson (persona) oder die Lernenden (learner); am Telefon ist das, wer abnimmt, und daraus folgt, wer angerufen hat
• RTSPPersona.virtualEmbodiment.profileImage — Profilbild samt Metadaten und erzeugendem Modell
• RTSPPersona.virtualEmbodiment.voice — Stimmprofil, anbieterneutral beschrieben (Sprache, Lage, Tempo, Klang) und je Anbieter und Modell der konkreten Stimme zugeordnet, damit eine Anwendung sie automatisch wählen kann

Der Auslöser je Aussage (RTSPStatement.trigger) ist ebenfalls Kandidat; er liegt unterhalb der Bindungsebene und erscheint deshalb nicht in der Liste.

Davon zu unterscheiden sind die Änderungsanträge in data/proposals.json: Felder, die es auch im Schema noch nicht gibt.

• RTSPCase.aiConfig.channel
• RTSPCase.aiConfig.focusedVirtualSPCompetencies
• RTSPCase.aiConfig.openedBy
• RTSPCase.shortDescription
• RTSPPersona.virtualEmbodiment.profileImage
• RTSPPersona.virtualEmbodiment.voice

Entscheidungen

Architekturentscheidungen zu diesem Standard liegen im Repository unter docs/adr/.

Lizenz

Veröffentlicht unter den Bedingungen der MIT-Lizenz; der Text liegt als LICENCE im Paket.