Protocol Schema Information 

Summary

Interviewer and Architect (from version 4.2.0 onward) implement a feature that tracks the version of the protocol file format, or "schema", associated with protocols that you author. You may notice messaging within the app that informs you of "out of date", or "obsolete" schema versions associated with your protocol. This article will explain these concepts in greater detail.

The key takeaway is that as long as your schema is not marked "obsolete", you can continue to use Interviewer to collect and export data, exactly as before.

Although every effort is made to maintain compatibility with new schema versions, any features implemented that require a schema update will be unavailable to you until you migrate your protocol. We strongly encourage you to update your protocol files wherever possible, so that you are able to use the newest Network Canvas features.

What is a protocol schema?

A protocol "schema" is a description of the structure of a protocol file. It takes the form of a series of constraints and logical rules that define property names, data types, and so on. When a protocol is used within Architect or Interviewer, it is validated against a schema. Unexpected values, properties, or structures will trigger various types of warning or error message.

Why do we need protocol schemas?

We need to "version" Network Canvas protocol schemas so that we can add or change features as we develop them. This could mean implementing a new interface, or changing the way that an existing function, such as skip logic, works. Simply changing an existing schema would make previously authored protocols invalid, or would lead to the software crashing.

We also adopted schemas in an effort to ensure stability and consistency within the functioning of the software. If a protocol is valid according to its schema, it should function without issues.

Our priority when implementing schema versioning has been to not burden the end user, either through creating "maintenance work" (for example by requiring older protocols to be updated manually), or by disrupting your workflow (for example by preventing existing protocols from functioning).

What it means for you

When you update Interviewer or Architect, you may encounter messages when using protocols that were authored in prior versions of the apps.

Within Interviewer

In Interviewer, you may see a blue light bulb icon, or a red robot icon, on your protocol card. Where a new schema is backward-compatible with a prior version you will see a blue light bulb, and Interviewer will continue to support installing and running protocols of that version without any issues. This means that if you are happy with your protocol file you do not need to take any action. Your protocol will continue to function as before, albeit without access to new functionality implemented with the new schema version (see the schema versions table below for details on this).

If you wish to update the protocol file to the new schema version, follow the instructions provided below under migrating a protocol.

If your protocol is no longer compatible with the version of Interviewer that you have installed, you will see a red robot icon, and will no longer be able to start an interview. Please see the section below on handling obsolete protocols for further assistance.

Within Architect

In Architect, you may see a prompt that a protocol must be migrated to a newer version before it can be opened (see below).

If you wish to update their protocol file to the new schema version, follow the instructions provided below under migrating a protocol.

If you would like to continue editing this protocol without migrating it to the latest version, you will need to downgrade your version of Architect. See the GitHub releases page for an archive of old versions, and consult for the compatibility table for information about which version you need.

Handling obsolete protocols

Although we aim to always make schema changes that are backward-compatible, this can be unavoidable if we need to substantially revise a feature. If a new schema version is implemented that is not backward-compatible, the user interface in Interviewer will mark the protocol as "obsolete" and will no longer allow new interview sessions to be started. Although this is obviously undesirable, all existing session data will continue to be exportable from a protocol in this state. Review the section below to understand your options in this scenario.

Although obsolete protocols will still be able to be migrated to the latest schema version by Architect, in some cases manual intervention or updating may be required. For example, if we add required properties to the protocol that cannot be derived from existing properties, you may need to create these yourself. Please contact us if you have encountered an issue, or have specific concerns about this.

What to do if your protocol is marked as obsolete

If your protocol is marked as obsolete, and you wish to continue collecting data using it, you have two options:

1. Migrate the protocol to a later version, which is compatible with your version of Interviewer. See migrating a protocol below for this.
2. Downgrade an older version of Interviewer, by uninstalling your current version, and downloading the version you require from our GitHub releases page. As per the warning at the start of this article, downgrading is not possible on iOS or Android platforms. If you have mistakenly upgraded your Interviewer version on these platforms causing your protocol to become obsolete, your only choice is to migrate your protocol to the latest schema version and to redeploy it.

Migrating a protocol

Migrating a protocol happens within Architect, and is automatic. The process works as follows:

1. Ensure you are on the latest version of the Architect app. When opening the app with an active internet connection, the app will check for updates automatically, and notify you if any are found. Alternatively, you can manually update the app, by visiting our download page and installing the latest version for your platform.
2. Once you are running the latest version, open the protocol file that you wish to migrate.
3. Architect will inform you that the protocol file can be upgraded, which happens by creating a copy (so that your original file is preserved). If you choose to continue, you will be prompted for a location to save your upgraded protocol.
4. Architect will automatically append "(schema version X)" to the filename, which may help you to keep track of the different versions of your protocol, and to differentiate them within Interviewer.

Compatibility Table

Consult the table below for information about which schema versions are supported by each released version of the Network Canvas software.

Technical implementation of schema migration

The following section may be useful if you are attempting to understand how schema migration is performed on a technical level. In rare cases, this may help you to troubleshoot an issue with a migrated protocol yourself, should you wish.

• A migration between two sequential schema versions is a functional transformation of the protocol object. These transformations are written as simple functions that take a protocol object, mutate it, and return the mutated protocol. Migration functions are defined in the protocol-validation submodule.
• Transformations can be chained together, meaning that a protocol can be migrated from version 1 to version n by applying all transformations in between in sequence [1 … n].
• We plan a parallel system of "patching", which will use the same technique as migration, but is designed to address any data corruption issues caused as a result of bugs in Architect. Patches are designed to fix protocol issues without updating the schema version.