Stanford Spezi FHIR Implementation Guide
0.1.0 - ci-build

Publish Box goes here

Questionnaires

Questionnaires and Surveys

Spezi applications provide comprehensive support for creating interactive healthcare questionnaires and surveys using industry-standard FHIR Questionnaires. The framework leverages the ResearchKitOnFHIR library in conjunction with SpeziQuestionnaire to convert FHIR Questionnaires into native ResearchKit surveys and serialize results back to FHIR QuestionnaireResponse resources.

ResearchKitOnFHIR supports FHIR Questionnaires that conform to the SDC (Structured Data Capture) Questionnaire profile and extends functionality with iOS-specific extensions.

Example: PHQ-9 Depression Screening

The following example demonstrates a complete implementation of the PHQ-9 (Patient Health Questionnaire-9) depression screening tool that can be rendered by ResearchKitOnFHIR.

{
  "resourceType": "Questionnaire",
  "id": "phq-9-depression-screening",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire"
    ]
  },
  "identifier": [
    {
      "system": "http://spezi.stanford.edu/questionnaire-identifiers",
      "value": "PHQ-9-v1.0"
    }
  ],
  "name": "PHQ9DepressionScreening",
  "title": "Patient Health Questionnaire-9 (PHQ-9)",
  "status": "active",
  "subjectType": ["Patient"],
  "date": "2024-01-15",
  "publisher": "Stanford Spezi",
  "description": "The PHQ-9 is a validated screening tool for depression severity in healthcare settings.",
  "contained": [
    {
      "resourceType": "ValueSet",
      "id": "phq9-answers",
      "status": "active",
      "compose": {
        "include": [
          {
            "system": "http://spezi.stanford.edu/fhir/CodeSystem/phq9-answers",
            "concept": [
              {
                "code": "0",
                "display": "Not at all",
                "extension": [
                  {
                    "url": "http://hl7.org/fhir/StructureDefinition/ordinalValue",
                    "valueDecimal": 0
                  }
                ]
              },
              {
                "code": "1",
                "display": "Several days",
                "extension": [
                  {
                    "url": "http://hl7.org/fhir/StructureDefinition/ordinalValue",
                    "valueDecimal": 1
                  }
                ]
              },
              {
                "code": "2",
                "display": "More than half the days",
                "extension": [
                  {
                    "url": "http://hl7.org/fhir/StructureDefinition/ordinalValue",
                    "valueDecimal": 2
                  }
                ]
              },
              {
                "code": "3",
                "display": "Nearly every day",
                "extension": [
                  {
                    "url": "http://hl7.org/fhir/StructureDefinition/ordinalValue",
                    "valueDecimal": 3
                  }
                ]
              }
            ]
          }
        ]
      }
    }
  ],
  "item": [
    {
      "linkId": "phq9-intro",
      "type": "display",
      "text": "Over the last 2 weeks, how often have you been bothered by any of the following problems?",
      "extension": [
        {
          "url": "http://hl7.org/fhir/StructureDefinition/rendering-styleSensitive",
          "valueString": "emphasis"
        }
      ]
    },
    {
      "linkId": "phq9-1",
      "type": "choice",
      "text": "Little interest or pleasure in doing things",
      "required": true,
      "extension": [
        {
          "url": "http://hl7.org/fhir/StructureDefinition/questionnaire-itemControl",
          "valueCodeableConcept": {
            "coding": [
              {
                "system": "http://hl7.org/fhir/questionnaire-item-control",
                "code": "radio-button"
              }
            ]
          }
        }
      ],
      "answerValueSet": "#phq9-answers"
    },
    {
      "linkId": "phq9-2", 
      "type": "choice",
      "text": "Feeling down, depressed, or hopeless",
      "required": true,
      "extension": [
        {
          "url": "http://hl7.org/fhir/StructureDefinition/questionnaire-itemControl",
          "valueCodeableConcept": {
            "coding": [
              {
                "system": "http://hl7.org/fhir/questionnaire-item-control",
                "code": "radio-button"
              }
            ]
          }
        }
      ],
      "answerValueSet": "#phq9-answers"
    },
    {
      "linkId": "phq9-score",
      "type": "integer",
      "text": "Total PHQ-9 Score",
      "extension": [
        {
          "url": "http://hl7.org/fhir/StructureDefinition/questionnaire-hidden",
          "valueBoolean": true
        },
        {
          "url": "http://hl7.org/fhir/StructureDefinition/minValue",
          "valueInteger": 0
        },
        {
          "url": "http://hl7.org/fhir/StructureDefinition/maxValue", 
          "valueInteger": 27
        }
      ]
    }
  ]
}

Corresponding QuestionnaireResponse

When a patient completes the survey, ResearchKitOnFHIR generates a FHIR QuestionnaireResponse:

{
  "resourceType": "QuestionnaireResponse",
  "id": "phq9-response-example",
  "questionnaire": "Questionnaire/phq-9-depression-screening",
  "status": "completed",
  "subject": {
    "reference": "Patient/example-patient"
  },
  "authored": "2024-01-15T14:30:00Z",
  "source": {
    "reference": "Patient/example-patient"
  },
  "item": [
    {
      "linkId": "phq9-1",
      "answer": [
        {
          "valueString": "Several days",
          "extension": [
            {
              "url": "http://hl7.org/fhir/StructureDefinition/ordinalValue",
              "valueDecimal": 1
            }
          ]
        }
      ]
    },
    {
      "linkId": "phq9-2",
      "answer": [
        {
          "valueString": "More than half the days",
          "extension": [
            {
              "url": "http://hl7.org/fhir/StructureDefinition/ordinalValue",
              "valueDecimal": 2
            }
          ]
        }
      ]
    },
    {
      "linkId": "phq9-score",
      "answer": [
        {
          "valueInteger": 3
        }
      ]
    }
  ]
}

Supported FHIR Extensions

The ResearchKitOnFHIR library supports a comprehensive set of standard HL7 FHIR extensions to enhance questionnaire functionality and provide rich user experiences on mobile platforms.

Questionnaire Item Control Extensions

These extensions control how survey items are rendered and behave:

questionnaire-itemControl

Defines the UI control type for survey items, enabling rich interactive elements:

{
  "extension": [
    {
      "url": "http://hl7.org/fhir/StructureDefinition/questionnaire-itemControl",
      "valueCodeableConcept": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/questionnaire-item-control",
            "code": "slider"
          }
        ]
      }
    }
  ]
}

Supported Control Types:

  • slider: Continuous value selection with visual feedback
  • drop-down: Compact selection from multiple options
  • radio-button: Single selection from visible options
  • check-box: Multiple selection capability
  • text-box: Free-text input with platform keyboard optimization

questionnaire-hidden

Controls conditional display and survey logic:

{
  "extension": [
    {
      "url": "http://hl7.org/fhir/StructureDefinition/questionnaire-hidden",
      "valueBoolean": true
    }
  ]
}

questionnaire-sliderStepValue

Configures precision and increments for slider controls:

{
  "extension": [
    {
      "url": "http://hl7.org/fhir/StructureDefinition/questionnaire-sliderStepValue",
      "valueDecimal": 0.1
    }
  ]
}

2.2.1.2 Validation Extensions

Comprehensive input validation ensures data quality and user experience:

regex

Pattern-based validation for text inputs:

{
  "extension": [
    {
      "url": "http://hl7.org/fhir/StructureDefinition/regex",
      "valueString": "^\\d{3}-\\d{2}-\\d{4}$"
    }
  ]
}

validationtext

Custom validation messages provide clear user feedback:

{
  "extension": [
    {
      "url": "http://bdh.stanford.edu/fhir/StructureDefinition/validationtext",
      "valueString": "Please enter a valid Social Security Number (XXX-XX-XXXX)"
    }
  ]
}

Value Constraint Extensions

Precise control over acceptable input ranges:

minValue / maxValue

Numerical range constraints:

{
  "extension": [
    {
      "url": "http://hl7.org/fhir/StructureDefinition/minValue",
      "valueDecimal": 0
    },
    {
      "url": "http://hl7.org/fhir/StructureDefinition/maxValue", 
      "valueDecimal": 10
    }
  ]
}

minValueDate / maxValueDate

Date range constraints for temporal data:

{
  "extension": [
    {
      "url": "http://hl7.org/fhir/StructureDefinition/minValue",
      "valueDate": "1900-01-01"
    },
    {
      "url": "http://hl7.org/fhir/StructureDefinition/maxValue",
      "valueDate": "2024-12-31"
    }
  ]
}

maxDecimalPlaces

Precision control for decimal inputs:

{
  "extension": [
    {
      "url": "http://hl7.org/fhir/StructureDefinition/maxDecimalPlaces",
      "valueInteger": 2
    }
  ]
}

Presentation Extensions

Enhanced visual presentation and user experience:

questionnaire-unit

Display units for quantitative values:

{
  "extension": [
    {
      "url": "http://hl7.org/fhir/StructureDefinition/questionnaire-unit",
      "valueCoding": {
        "system": "http://unitsofmeasure.org",
        "code": "kg",
        "display": "kilograms"
      }
    }
  ]
}

entryFormat

Input format hints and placeholder text:

{
  "extension": [
    {
      "url": "http://hl7.org/fhir/StructureDefinition/entryFormat",
      "valueString": "MM/DD/YYYY"
    }
  ]
}

ordinalValue

Numeric scoring for assessment scales:

{
  "answerOption": [
    {
      "extension": [
        {
          "url": "http://hl7.org/fhir/StructureDefinition/ordinalValue",
          "valueDecimal": 0
        }
      ],
      "valueString": "Not at all"
    },
    {
      "extension": [
        {
          "url": "http://hl7.org/fhir/StructureDefinition/ordinalValue", 
          "valueDecimal": 3
        }
      ],
      "valueString": "Nearly every day"
    }
  ]
}

rendering-styleSensitive

Advanced styling hints for visual presentation:

{
  "extension": [
    {
      "url": "http://hl7.org/fhir/StructureDefinition/rendering-styleSensitive",
      "valueString": "emphasis"
    }
  ]
}

Platform-Specific Extensions (iOS)

iOS-optimized input experiences:

Keyboard Type Specifications

{
  "extension": [
    {
      "url": "http://bdh.stanford.edu/fhir/StructureDefinition/ios-keyboardtype",
      "valueString": "numberPad"
    }
  ]
}

Autocapitalization Preferences

{
  "extension": [
    {
      "url": "http://bdh.stanford.edu/fhir/StructureDefinition/ios-autocapitalizationType",
      "valueString": "words"
    }
  ]
}

Content Type Hints

{
  "extension": [
    {
      "url": "http://bdh.stanford.edu/fhir/StructureDefinition/ios-textcontenttype",
      "valueString": "emailAddress"
    }
  ]
}