Review request: validated questionnaires as openEHR templates – with the FHIR mapping inside the Questionnaire

Clinical CKM publication
1

Hi all,

I’d love this community’s critical eye on a set of questionnaires I modelled in openEHR. I’m posting this in a personal capacity. I built them while working on a regional openEHR platform in the Netherlands, which is why you will see some Dutch project names in the files.

Ian McNicoll suggested I raise this here, and that PROMs are a tricky area. @Koray Atalag, as lead of the PROMs work group, I would especially value your view.

What I built

The Dutch national bodies Nictiz and IKNL publish validated questionnaires as FHIR Questionnaires. I converted 66 of them into openEHR. Each questionnaire now exists as:

  • an openEHR template (running in EHRbase), and
  • a FHIR Questionnaire (running in HAPI) that the patient fills in.

The trick is that the Questionnaire carries the mapping. It names its template, every item gives the AQL path of its element, and every answer option has the archetype at-code as its code and the score as ordinalValue. openFHIR turns a QuestionnaireResponse into a composition with nothing configured per questionnaire:

patient app (SDC) ─► QuestionnaireResponse ─► openFHIR ─► EHRbase ─► AQL / registries / OMOP

English first

All archetypes have English as their original language, with Dutch as a translation:

  • For the international instruments I used the official English wording wherever it exists and may be used.
  • For the rest (MRC, NRS and the Dutch forms) I translated the Dutch myself. Those translations have not yet been reviewed by a clinician.

The package (links at the bottom)

22 questionnaires. For each one: the template (OPT and OET) and the FHIR Questionnaire, exactly as they run in EHRbase and HAPI. All archetypes the templates use are in a separate folder, so you can load everything into Archetype Designer.

  • 14 international instruments: PHQ-9, PHQ-2, GAD-7, DASS, RAID, WHO-5, MRC, cPTCI, ACQ, BSQ, ICS, AQ, and NRS pain and fatigue. The templates are English.
  • 8 Dutch forms: the Global Perceived Effect scales, three items from the Dutch arthroplasty registry (LROI) and two national care documentation forms (advance care planning, breast radiology). Their templates and Questionnaires are Dutch first; the archetypes are English.

The Questionnaires are bilingual through the FHIR translation extension, and the patient app picks the device language. Answers are stored as codes, so the language doesn’t affect the data.

I modelled 44 more questionnaires the same way. They are not in the package because they are copyrighted (EQ-5D-5L, OKS, KOOS and others) or have no freely usable English version. The README explains everything in one page.

What I’d like to hear

  1. One OBSERVATION archetype per instrument where CKM has none (PHQ-9 and GAD-7 do use CKM). Is that the right approach?
  2. Componentised instruments and variants. Ian pointed out that PROMIS is a special case because its authors explicitly built it from components. PROMIS is not in this set, but the question applies more widely. Some of mine are families that share one archetype: PSK for several conditions, GPE with 1 or 2 items, the AQ self-report and partner versions, ICOAP for hip and knee. How should instrument families and components be modelled?
  3. DV_ORDINAL vs DV_CODED_TEXT, and where to put total and subscale scores. Cut-offs (e.g. WHO-5 below 13, the DASS and PHQ-9 severity bands) are now only described in the score element. Would you add a separate interpretation or category element?
  4. self_reported_data.v1 as the composition for PROMs. Is that right?
  5. Putting the openEHR binding inside the FHIR Questionnaire. Sensible, or is there an approach I should align with?
  6. Multilingual questionnaires. English in the archetypes and FHIR translations for the patient: is that the right split? Or should the templates carry the languages too?
  7. Local variants of an instrument. The Dutch MRC dyspnoea scale has 6 levels (0–5, with an extra “not troubled by breathlessness”); the original MRC has 5 grades, and the mMRC has 5 (0–4). Should a variant like this be its own archetype, a constraint on one MRC archetype, or something else? And what should it be called?
  8. The things around the archetype.
    • Every template carries a local CLUSTER.regional_context.v0 in the composition context. Would you do that differently?
    • The Fair Questionnaires use my own extensions (openehr-template-source, openehr-aql-path), which have no published StructureDefinitions yet. Is there a better-known extension I should use?
    • The Fhir Questionnaires have status draft until they are approved for use.
    • The template ids are internal ids from the project, with the version in the id (RSO-ZL Vragenlijst PHQ-9.v10). Would you expect a different naming and versioning convention?
  9. CKM. Would any of these be welcome as proposals? DASS is first in line.

All comments are welcome, small or large. Thanks!

Igor Schoonbrood

Files: GitHub - ITCAdvies/openehr-questionnaires-review: Review package: Dutch validated questionnaires as openEHR templates and bilingual FHIR Questionnaires (RSO Zuid-Limburg / ITCAdvies) · GitHub – browse the files online, or download everything as one zip: https://github.com/ITCAdvies/openehr-questionnaires-review/releases/download/v2026-10-13/rsozl-questionnaires-openehr-fhir.zip

6 Likes