Questionnaires and YAML format

In this document you will find some information about the YAML format, our use of questionnaries and the data mappings we have available to interoperate with other systems.*

Introduction

In Lotus AI, we use the FHIR Questionnaire resource to represent questionnaires. The FHIR Questionnaire resource provides a standard for representing questionnaires in healthcare applications.

We have extended the FHIR Questionnaire resource with some custom item types to better suit our needs. For example, we have added a date item type for date inputs and a select item type for dropdown inputs.

We represent our questionnaires in YAML format because it's human-readable and easy to work with.

Questionnaires

When we read the YAML file we translate the content into a FHIR Questionnaire resource. We append some default values to reduce the amount of repeated attributes and attempt to make it easier to interpret.

In this example, we define a Questionnaire resource with a title, name, status, description, identifier, extension, and array of items. The items array contains the questions in the questionnaire.

resourceType: Questionnaire
title: Default Questionnaire
name: Default Questionnaire
status: inactive
description: Questionnaire with default values
identifier:
  - system: https://dev.lotuscares.ai/api/extensions/form_id
    value: default-form
extension:
  - url: https://dev.lotuscares.ai/api/extensions/slug
    valueString: consent
  - url: https://dev.lotuscares.ai/api/extensions/form_category
    valueString: CNS
item:
  - linkId: t1
    text: Procedural consent form
    type: title
  - linkId: Patient.Smokes
    text: Do you smoke?
    answerOption:
      - valueString:  No
      - valueString:  Yes
  - linkId: Patient.ssn
  - linkId: Patient.email

Available Data Types

We have extended the FHIR Questionnaire resource with some custom item types to better suit our needs. Here are the available data types:

group
display
question
boolean
decimal
integer
date
dateTime
time
string
text
url
choice
openChoice
attachment
reference
quantity
signature
paragraph
title
initials
yesno
markdown

Special data types require to use a special format to include the answers, some of these allow to include CPT codes, SNOMED codes, and other medical codes. Those will be store alongside the answers in the FHIR Questionnaire Response resource.

For example an item of type choice expects an answerOption array with the possible answers.

type: choice
linkId: Patient.Smokes
answerOption:
  - valueString:  No
  - valueString:  Yes

markdown

The item type of markdown will transform the text into a markdown format, this is useful to include rich text in the questionnaires.

item:
  type: markdown
  text: |
    # Heading 1

    ## Subtitle

    Emphasis, aka italics, with *asterisks* or _underscores_.

    Strong emphasis, aka bold, with **asterisks** or __underscores__.

    Combined emphasis with **asterisks and _underscores_**.

    Strikethrough uses two tildes. ~~Scratch this.~~

    **This is bold text**

    __This is bold text__

    *This is italic text*

    _This is italic text_

    ~~Strikethrough~~

Learn more about markdown syntax in the Markdown Guide.

Data mappings

Every question has a linkId property, we use this to map data bidirectionaly with the EMR to store and retrieve the data.

We can use the linkId to generate preset values for the questions, and simplify the YAML file.

The available mappings are:

{
  'Patient.ssn': { type: 'string', text: 'SSN' },
  'Patient.name.text': { type: 'string', text: 'Full Name' },
  'Patient.name.first': { type: 'string', text: 'First Name' },
  'Patient.name.middle': { type: 'string', text: 'Middle Name' },
  'Patient.name.last': { type: 'string', text: 'Last Name' },
  'Patient.gender': { type: 'string', text: 'Gender' },
  'Patient.birthDate': { type: 'string', text: 'Birth Date' },
  'Patient.maritalStatus': { type: 'string', text: 'Marital Status' },
  'Patient.email': { type: 'string', text: 'Email' },
  'Patient.address': { type: 'string', text: 'Address' },
  'Patient.employer.name': { type: 'string', text: 'Employer Name' },
  'Patient.employer.address': { type: 'string', text: 'Employer Address' },
  'Patient.employer.city': { type: 'string', text: 'Employer City' },
  'Patient.employer.state': { type: 'string', text: 'Employer State' },
  'Patient.employer.postalCode': { type: 'string', text: 'Employer Postal Code' },
  'Patient.employer.phone': { type: 'string', text: 'Employer Phone' },
  'Patient.employer.jobTitle': { type: 'string', text: 'Employer - Job Title' },
  'Patient.employer.email': { type: 'string', text: 'Employer Email' },
  'Patient.extension.race': { type: 'choice', text: 'Race'},
  'Patient.extension.ethnicity': { type: 'choice', text: 'Ethnicity'},
  'Patient.address.line0': { type: 'string', text: 'Address line 1' },
  'Patient.address.line1': { type: 'string', text: 'Address line 2' },
  'Patient.address.city': { type: 'string', text: 'City' },
  'Patient.address.state': { type: 'string', text: 'State' },
  'Patient.address.postalCode': { type: 'string', text: 'Zipcode' },
  'Patient.emergencyContact.name': { type: 'string', text: 'Contact Name' },
  'Patient.emergencyContact.firstName': { type: 'string', text: 'Contact First Name' },
  'Patient.emergencyContact.lastName': { type: 'string', text: 'Contact Last Name' },
  'Patient.emergencyContact.phone': { type: 'string', text: 'Contact Phone Number' },
  'Patient.emergencyContact.line0': { type: 'string', text: 'Contact Addres line 1' },
  'Patient.emergencyContact.line1': { type: 'string', text: 'Contact Addres line 2' },
  'Patient.emergencyContact.city': { type: 'string', text: 'Contact Addres city' },
  'Patient.emergencyContact.state': { type: 'string', text: 'Contact Addres state' },
  'Patient.emergencyContact.postalCode': { type: 'string', text: 'Contact Addres postal code' },
  'Patient.emergencyContact.relationshop': { type: 'string', text: 'Contact Relationship' },
  'Patient.telecom.value': { type: 'string', text: 'Phone Number' },
  'Document.Date': { type: 'date', text: 'Date' },
  'Patient.Coverage.InsuranceCard': { type: 'attachment', text: 'Insurance Card' },
  'Patient.Coverage.Primary.InsuranceCard': { type: 'attachment', text: 'Primary Insurance Card' },
  'Patient.Coverage.Secondary.InsuranceCard': { type: 'attachment', text: 'Secondary Insurance Card' },
  'Coverage.Primary': { type: 'coverage', text: 'Primary insurace' },
  'Coverage.Secondary': { type: 'coverage', text: 'Secondary insurace' },
  'Patient.Coverage.PrimaryInsurance': { type: 'string', text: 'Primary Insurance' },
  'Patient.Coverage.PrimaryPolicyID': { type: 'string', text: 'Primary Policy ID' },
  'Patient.Coverage.PrimaryGroupNumber': { type: 'string', text: 'Primary Group Number' },
  'Patient.Coverage.SecondaryInsurance': { type: 'string', text: 'Secondary Insurance' },
  'Patient.Coverage.SecondaryGroupNumber': { type: 'string', text: 'Secondary Group Number' },
  'History.familyMember': { type: 'text', text: 'Family Member History' },
  'History.social': { type: 'text', text: 'Social History' },
  'History.surgical': { type: 'text', text: 'Surgical History' },
  'History.medical': { type: 'text', text: 'Medical History' },
  'History.specialists': { type: 'text', text: 'Specialists' },
  'Form.startTime': { type: 'dateTime', text: 'Start Time', extension: [hiddenExtension] },
  'Form.endTime': { type: 'dateTime', text: 'Submit Time', extension: [hiddenExtension] },
  'Form.duration': { type: 'string', text: 'Duration', extension: [hiddenExtension] },
  'Screening.score': { type: 'integer', text: 'Score', extension: [hiddenExtension] },
  'Screening.*': { type: 'choice', text: 'Screening questions',},
}

In the lotus-ts repo, find example questionnaires in the src/models/resources/questionnaires/ directory.

Integrations

Our questionnaires are designed to be interoperable with other systems. We use the FHIR standard, which is widely adopted in the healthcare industry, to ensure that our questionnaires can be easily integrated with other FHIR-compliant systems.

We also provide a Medplum integration, which allows you to use our questionnaires with Medplum's FHIR server. This makes it easy to store and retrieve questionnaire data, and to use Medplum's features to manage and analyze the data.

For more information about the FHIR Questionnaire resource and our custom item types, please refer to the:

• Questionnaire Medplum Documentation.
• Questionnaire Response Medplum Documentation

Code Editors

We recommend using a code editor with YAML support to work with our questionnaires. Some popular code editors with YAML support include:

• Visual Studio Code
• Online YAML Editor

Conclusion

We hope this document has provided you with a better understanding of how we use questionnaires and the YAML format in Lotus AI.

Back to the documentation.

Footnotes

*Only available for custom integrations.