This is currently a collection of notes on possible categories for app level demographics.

• Ideally, the demographics are collected once for a participant during their first enrollment in a study. Future enrollments should not need to repeat that process in the same app assuming the demographic questions are consistent.

• The information collected initially could change so updates need to be possible.

• At least for different apps, the available answers for various categories (and which categories are necessary) could vary. So the categories/values will most likely be determined in the app config.

• Demographic info could be used to determine which group or schedule a participant will be assigned. So totals by answer will need to be fairly easy to query.

• Checking adherence across a group might also be necessary.

Sample categories:

• Race (enum)

• Ethnicity (enum)

• Education (enum)

• Sex (enum)

• Gender (enum)

• Disease (enum?)

• Date Year of Birth

• Blood Pressure (two scalars?)

• Height (scalar, what UOM?)

• Weight (scalar, what UOM?)

• Country Code (enum)

• Language (enum)

• Postal Code Prefix (scalar)

• Employment Status (enum)

• Occupation (enum? write in?)

• Dwelling

• Veteran Status (enum)

• Disability Status (enum)

• Marital Status (enum)

• Income (enum categories?)

• Religious Affiliation (enum)

• Political Affiliation (enum)

• Sexual Orientation (enum)

• Custom? (Would this be possible or even useful?)

Answer formats:

• Choose one

• Choose multiple

• Required (A question shouldn’t be asked if it’s not required.)

• Skippable (Would at least require an opt-out.)

• Explicitly opt-out (Are there times when a “Do not wish to answer” option is presented?)

• Other as option (would write-in ever be useful?)

Possible Endpoints:

• v3/participant/{userId}/demographics

  • POST - Create demographics

    • Expects list of demographics for the userId given in the path

      {[ { "category": "education", "value": "kinder" }, { "category": "height", "value": 30 }, { "category": "language", "value": ["english", "spanish"] } ]}

    • Alternatively, could have the create only add one demographic at a time. Seems better to do it in a list and reduce the requests necessary to the server.

  • GET - Get all demographics for a participant

    • Would return a list like the one sent in a “create” request.

• v3/participant/{userId}/demographics/update

  • POST - Update demographics

    • If versioning is not required, then this route is probably not necessary. The “create” route could just update any existing categories.

    • Expects a single demographic (could be a list but it seems less likely that multiple will be submitted on an update)

      { "category": "education", "value": "grad" }

• v3/participant/{userId}/demographics/{category}

  • GET - Get participant demographic

    • Would only be able to return one demographic category

  • DELETE - Delete demographic

    • Delete a single demographic category record for a participant

• v5/study/{studyId}/participants/demographics/search

  • GET - Get a list of demographics based on query parameters

    • The returned list could be a paged resource list to handle the possible size.

    • This might need to be a POST route instead, allowing for more detailed requests. (For instance, if the requester wanted the demographics of 50 specific users by passing in their IDs)

• v5/study/{studyId}participants/demographics/summary

  • GET - Get a summary of demographic totals for a study

    • Returns categories with values mapped to totals.

      { "education": { "kinder": 5, "grad": 8 }, "height": { "30": 4, "40": 3, "50": 6 }, "language": { "spanish": 8, "english": 7, "french": 5 } }

    • This would be easiest to implement if it calculated totals on request, harder if it tracks and updates totals during other requests.

• GET for list of categories? Enumerated values? Might not be necessary if those are determined by the app config.

Q: How do we decide what is too specific? Is it a population cutoff? As in some combination of answers could represent a group of less than 50 people?

• This is more of a requirement for the app/study designer. But each of these categories can be somewhat controlled through the values allowed.

Q: Say one app wants Age in 10s and another in 20s. Can the category values be set in the app config? Is that where they are enumerated?

Q: Would there ever be a situation where the app config for these categories actually drives how the questions are displayed? As in, would an app look through the list to determine whether to use check boxes or radio buttons depending on the answer format. Or would there need to be a “visible label” option in the config in case someone needs to title the education questions “Years of Study”.

Q: Is there a way to make the data easier to query for groups (get all participants with English language, Veteran, 123 postal code)? Is that even an expected use case?

Q: Is there a need for version tracking when updating demographics? For instance, if a participant moves from one country to another and updates their country code, would keeping a record or their initial country code and date be necessary?

Config:

"bridge:demographics": {
  "education": {
    "type": "enum",
    "values": ["kinder","pre","grad"],
    "format": "1"
  },
  "height": {
    "type": "int",
    "max": 120,
    "min": 12,
    "format": "1"
  },
  "language": {
    "type": "enum",
    "values": ["english","spanish","french"],
    "format": "+"
  }
}

Data: