How to name property that contains questions/widgets list

[xamelon]

Description

1. Form exists as a visual representation of questions, images, free text
   and other visual elements(widgets) that help to capture information from the end user.

2. Form DSL should describe questions and their visual representation in one place - to simplify form creation by removing duplication.
   It also should provide a way to describe other visual elements (widgets).

3. Form DSL should contain a place where to put question/widget definitions.

4. In current Aidbox SDC DSL we define questions data model in one place (Document DSL),
   but question's visual definition and widget's definition in another place (Layout DSL).

5. In current Aidbox SDC Document DSL ZEN language built-in schemas are used to describe
   Form's data-model. That gives a data constraints definition and zen/validation for free.
   zen/map schema is used as form data-model definition, and :keys property(keys in a map)
   contains question's definitions, where key is a question id, and value is a question definition.

   Example:

   VitalsSigns
   {:type zen/map
    :keys {:blood-pressure {:type zen/map}
           :temperature    {:type zen/number}}}

6. FHIR Questionnaire has item property that holds questions and other visual elements,
   and FHIR has only one place to define that.

Problem

• how to name property that holds questions and widgets and is also clear from the user's perspective?
• should we go FHIR way to name this property?

Approach

Use Cases

User wants a good structured DSL in which every property is logical, intuitive and simple to remember.

Strategy

3 approaches of how to name property:

1. questions - straightforward name from Form problem domain
2. fields - all Forms constists of fields - that user can fill with data
3. items - just the same as FHIR/Questionnaire

Decision matrix

How to name the property	questions	fields	items
self-descriptive	good description	more related to UI (input fields in a Form) than to questions	not descriptive at all, too generic
obvious that holds questions and visual elements	not obvious that there are other elements	not obvious that it contain questions and 'display-only' widgets	there are can be anything - not just questions and widgets
memorable	good memorable effect	can be memorable	can be memorable by practice - FHIR/Questionnaire already has the same prop
close to FHIR	not but simple to infer	not	the same value

Design

name property questions or items

[xamelon]

Rename :keys to :questions

LateVisitDocument
{:type aidbox.sdc/form
 :questions [...]}}

Pros:

• semantic key name

Cons:

• form can contain not only questions (group, image)

[xamelon]

Rename :keys to :fields

LateVisitDocument
{:type aidbox.sdc/form
 :fields [...]}

Pros:

• more descriptive than keys

Cons:

• looks like model of layout, but not questionnaire

[xamelon]

Rename :keys to :items

LateVisitDocument
{:type aidbox.sdc/form
 :items [...]}

Pros:

• similar to fhir questionnaire

Cons:

• looks too abstract (what items holds?)