Surveys are one type of activity you can add to your study in Ethica, and arguably the most common activity participants do while in a research study. Surveys share all features of an Ethica Activity as we described previously, such as Triggering Logic, Notifications, and Criteria. If you have not reviewed these features already, we suggest you read about them first. In this section, we focus on features that are specific to the Surveys.

Survey Structure

Each survey in Ethica consists of one or more sections, and each section also contains one or more questions. Sections are used to group different questions, either because they are conceptually relevant, or to apply branching or loop iterations on them. Questions are the main building blocks of a survey that is presented to the participant in order to enter their responses.

Ethica app shows questions one by one to the participant. Participants will not see any notion of sections within your survey while responding to it. Sections are primarily used for grouping and flow management.

Surveys in Ethica are defined using a plain-text JSON document. The document describes when the survey should be prompted (the Triggering Logics), how the participant should be notified (the Notifications), what enables or disables a survey (the Criteria), what sections exist in the survey, what questions each section contains, what is the branching and skip patterns, and any other setting Ethica supports for surveys. All these settings are defined in a schema file called Ethica Survey Schema. When you create a survey activity, you can either use Ethica's graphical Survey Editor or define a JSON file and upload it as your survey. If you create and upload a JSON file, Ethica first validates it against the Survey Schema to make sure all settings are entered correctly.

Versions, Import and Export

To create a survey from your JSON file, you can upload the file to the Ethica website. To create a new survey based on your JSON file:

  1. Open Ethica Researcher Dashboard and navigate to the Activities section.
  2. Click on + New Activity.
  3. Select the Survey and then Import Survey. Import dialog in Activities
  4. Drop your JSON file to the drop-zone. This will start validating the JSON file.
  5. If the file is valid, a green checkmark is shown and you can click on Import to create your survey using this file. Import dialog shows a
validated JSON
  6. If the file is not valid, you will see an error and you will be asked to upload a new file. You can refer to JSON Content Validation for details on how to validate your JSON file.

You can also import a JSON file into your existing survey. To do so:

  1. Open the survey activity you want to modify.
  2. Go to the Preview & Publish -> Versions tab.
  3. There you will see the list of versions for your current survey.
  4. On top of the versions, click on Upload Survey Definition File. List of Survey Versions in the Survey Editor Preview &
  5. You will see a similar Import dialog as above. You can upload a valid survey JSON file there.
  6. When completed, the content of the file will be loaded to your survey as a draft. You can preview and then publish this survey.

Every time you publish your survey, a new version of that is created in Ethica. You can see the list of all versions in the Versions tab, along with other information such as when the survey was published, who published it, and what was the note left on that published version. For each version, you can click on Download Survey Definition File to download the content of that version as a survey JSON file.

You also can click on Load this version to load the selected version of the survey. This will create a new version of your survey with the content of the version you selected and sets it in the draft mode. For the last published version, you'll find a Revert to this version button instead. You can use that button to discard your draft changes.

JSON Content Validation

Ethica does not offer an advanced survey JSON validation. So if you try to upload a survey JSON file which is invalid, you will just see an error saying the file is not valid, but no more details on what is the issue in the file.

To get more information on exactly what is the problem with the file, you can use external JSON schema validators such as this option. On this website, you can upload the content of the Ethica Survey Schema on the left side, and the content of your survey on the right side. This will validate the content of the survey and shows you any problems or errors it finds:

Validate survey json file using JSON validation

Preview Survey

Before publishing your survey it's important to check it thoroughly to make sure there are no issues. The Preview tab in the Preview & Publish tab can help you with this. The following image shows how this tab looks like:

Preview view of Survey Editor Preview and Publish

There are two sections on this page. The right side of the page shows a preview of the survey. This preview can simulate exactly how the survey flow will be in the Ethica mobile or web app. From the top of the simulator, you can choose to preview a Desktop or Mobile View. This way you can see how your survey will look like on different screen sizes.

The right side of the page shows the list of criteria from other surveys that impact the flow of this survey. As we explained in the Criteria section, in Ethica you can define a criteria for a section or a question based on the responses to questions from other surveys in your study. The Preview tab detects such dependencies and loads those questions here on the left side.

By default these questions are not answered, so the Preview tab shows the flow if these questions were not answered. You can enter any answer to these questions, reload the Preview section, and start the survey again. This allows you to try out the flow of the survey using different assumptions.

For example, consider the above image. The survey there asks about the weight and height of the participant, and if they are female within 18 to 40 years old, also asks if they are pregnant. So the flow of the survey depends on the gender and the age of the participant, which is asked in a different survey. That's why on the left side, you can see Ethica lists two questions, one is asking the participant's gender, and the next one asking the participant's age:

Criteria Questions section in Preview tab of the Survey Editor Preview and

By default, these two questions have no answers. So the flow of the survey behaves as if the participant skipped responding to these questions. If you answer these questions, Ethica asks you to reload the survey in order to see the changes in the survey flow. You can click on the dialog, or click on the Reload button on the top right corner to apply this change:

Preview Reload in Preview tab of the Survey Editor Preview and

Publish Surveys

Any changes you make to the survey will be saved in the Draft mode. This means while the changes are saved, they are not accessible to the participants (both test participants and real participants), and you may revert them if they are not satisfactory. In order to make them available to the participants, you need to publish your changes.

You can publish your survey using the Publish tab of the Survey Editor's Preview & Publish section:

Publish tab of the Survey Editor's Preview & Publish

This section first runs validation on your survey to ensure all settings are done correctly. If there are any errors or warnings, you can see them under the Survey Validation part. You must resolve all errors before you can proceed with publishing your survey.

When all issues in your survey are resolved, or if there are no warnings or errors, you can press the Publish button to publish your survey. You can also leave a note on this to document what changes were made as part of this published version. This note will be available later on in the Version tab.

Additional Settings

Each survey offers a set of additional settings. You can access these settings by opening the Survey Editor, navigating to the Content tab, and opening the Settings tab in the lower right corner. Below we describe each of these configurations.


This specifies the criteria for the survey activity. This acts as the main criteria for the activity and supersedes the criteria set on the triggering logic. You can learn more about Activity and Triggering Logic criteria in the Criteria Section.

Section Randomization

You can randomize the order or the selection of the sections within your survey using the options available in the Section Randomization. The random selection allows you to choose a subset of sections within your survey, and also choose a selection count. Every time Ethica displays this survey, it selects a subset of the specified sections, where the size of the subset is the same as Selection Count. Then it displays these sections to the participant.

Similarly, you can enable the Random Section Order option. Doing so will randomize the order in which these sections are displayed.

Capture Location

This option instructs Ethica to capture participant's location while answering a given survey. When enabled, each response will be geo-tagged prior to the storage.

Note that this option is different from using Location data source in your study. When you add the Location data source to your study, the Ethica app will continuously capture participants' location, whether they are answering a survey or not. Such data is stored separately from the survey responses. While it is possible to join the data at a later stage to infer the participant's location at the time of answering a survey, this is not done automatically by Ethica.

On the other hand, Capture Location option makes sure all survey responses are geo-tagged, whether the Location data source is enabled or not, assuming the participant grants GPS permission to the Ethica app, and the GPS functionality is available and enabled on their phone.

By default, this option is turned off.

Show Progress

This option instructs Ethica to show the participants how many questions are left to answer in the current survey session. The following picture shows the same survey, with and without Show Progress option enabled:

Ethica Survey with Progress Display Ethica Survey without Progress Display
With Display Progress Without Display Progress

Note that the progress shown here is the approximate progress, and does not present the exact number of questions left to complete. Certain sections or questions might not be presented due to the defined branching, skip patterns, or randomized section selection. In this case, the participant will notice a jump in the progress.

By default, this option is turned on.