RIOS Documentation - media.readthedocs.org · RIOS Documentation, Release 0.3.0 Welcome! This site is the home of the documentation and speciﬁcations around RIOS, the Research Instrument

RIOS DocumentationRelease 0.3.0

Prometheus Research, LLC

Jan 31, 2020

Contents

1 Introduction 31.1 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 Specifications 72.1 Instrument Definition Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.2 Calculation Set Definition Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162.3 Assessment Document Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.4 Web Form Configuration Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272.5 SMS Interaction Configuration Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382.6 REXL - RIOS Expression Language Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

3 Examples 453.1 Example of a Simple Definition Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453.2 Example of All Data Types Being Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

4 License 614.1 Apache License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

5 Change History 655.1 RIOS Change History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

i

ii

RIOS Documentation, Release 0.3.0

Welcome! This site is the home of the documentation and specifications around RIOS, the Research Instrument OpenStandard.

Contents 1


2 Contents

CHAPTER 1

Introduction

1.1 Background

Table of Contents

• Background

– Overview

– About the Authors

1.1.1 Overview

Electronic data capture (EDC) systems have increasingly replaced paper-based methods of collecting research data.As EDC systems have proliferated, however, so has the number of incompatible formats for storing EDC instruments(form configurations). The lack of interoperability among EDC formats makes it difficult to reuse, share, or findpreviously configured instruments unless they were configured for the same EDC system. Ideally, each researchinstrument would need to be configured only once, would be stored in an easily accessible place for others to use, andwould work seamlessly with its users’ EDC tools.

The Research Instrument Open Standard (RIOS) brings this ideal closer to reality by laying the groundwork for aninteroperable ecosystem of research instruments. All EDC instruments have at least four types of properties: content(e.g., text of questions and response options), structure (e.g., ordering, grouping of questions), internal logic (e.g., skiplogic, validation rules), and method of display (e.g., pagination, form controls used to collect responses). RIOS is anopen metadata standard for representing research instruments. It offers a generic, well-defined schema for representingthe content, structure, logic, and display properties shared by all EDC instruments, without relying on the idiosyncraticrepresentations of EDC systems.

By moving to a standard research instrument definition, researchers can begin to develop converters to move instrumentconfigurations between EDC systems. Prototype converters for moving to and from the RIOS standard and Qualtrics

3

https://www.qualtrics.com/


and REDCap EDC formats are available at https://www.rexdb.org/rios-converter/. Applications built on the open-source RexDB platform (e.g., RexStudy) natively support the RIOS standard. More information about the RexDBproject can be found at https://www.rexdb.org/.

1.1.2 About the Authors

With funding from the NIH (Grant #1R43-MH106225), the informatics experts at Prometheus Research authored thefreely-available, universal standard called RIOS and initial set of conversion tools for the exchange, reuse, and storageof EDC metadata configurations. The original implementation of the standard was referred to as “PRISMH” for the“Portable Research Instrument Standard for Mental Health” and later renamed due to its applicability to domains out-side of mental and behavioral health. Webinar(s) and other resources about RIOS are freely available on Prometheus’website: http://www.prometheusresearch.com. For more Prometheus’-authored works, visit FigShare.

1.2 Overview

Table of Contents

• Overview

– Introduction

– Major Components

* Instrument

* Assessment

* Calculation Set

* Web Form

* SMS Interaction

1.2.1 Introduction

The RIOS specification describe a collection of configuration files that are used to define the process of data collectionin an open and transportable way.

1.2.2 Major Components

Instrument

Instrument Definition are the base of the RIOS specification. They contain the definition of what data is to be collected.At its heart, it is a list of field definitions that specify the name, data type, and type constraints. There is no informationor instruments on how the data is to be retrieved or collected – only what data needs to be collected.

Assessment

Assessment Documents are individual units of collected data that satisfy the rules defined in an Instrument. They area field-for-field listing of each data point, and can optionally contain metadata about the data or the means that wereused to collect it.

4 Chapter 1. Introduction

http://projectredcap.org/

https://www.rexdb.org/rios-converter/

http://www.prometheusresearch.com/rexstudy

https://www.rexdb.org/

http://www.prometheusresearch.com

https://figshare.com/search?q=prometheus+research


Calculation Set

Calculation Set Definitions are a means of augmenting an Instrument with additional fields that can be programmati-cally calculated using the data collected in an Assessment. These calculated values are then stored in their correspond-ing Assessment Document as metadata.

Web Form

Web Form Configurations are a generic way of describing how the data described by an Instrument should be collectedwhen the desired tool is a Web-based form. It describes what order the questions are presented in, how they’repaginated, what text is used to guide or prompt the user, and what web components are used to enter the data.

SMS Interaction

In much the same way that Web Form Configurations describe how to collect an Instrument’s data via a web page, SMSInteraction Configurations describe how to collect the data via an interactive SMS text message exchange. It describeswhat order the questions are presented in and what text is used to guide or prompt the user.

1.2. Overview 5


6 Chapter 1. Introduction

CHAPTER 2

Specifications

2.1 Instrument Definition Specification

Table of Contents

• Instrument Definition Specification

– Overview

– Format

– Structure

* Root Object

* Field Object

* Type Collection Object

* Type Object

* Column Object

* Row Object

* Base Types

* Bound Constraint Object

* Enumeration Collection Object

* Enumeration Object

* Identifier

* Metadata Collection Object

7


2.1.1 Overview

A RIOS Instrument Definition is a standard means to represent a set of data that must are to be collected about asubject. It is intended to define what data is to be collected, not necessarily how that data is collected.

2.1.2 Format

Instrument Definitions are stored and exchanged as JSON (JavaScript Object Notation) objects. The structure of theseobjects must adhere to the rules set forth in this document. When stored in files, these files must be UTF-8 encoded.

2.1.3 Structure

Root Object

The Root Object of an Instrument Definition consists of several properties:

id

Type String

Constraints Required; Must be a URI as described in RFC3986

Description This property contains a URI string that uniquely identifies the instrument describedwithin the definition. This id, in conjunction with the version property, is used by Assess-ment Documents (and/or other supplementary documents) to identify which Instrument Defini-tion they correspond to. Typically, urn-schemed URIs are used, but http -schemed URIs arealso valid.

Example urn:my-organization:an-instrument-name

version

Type String

Constraints Required; Must be formatted in a traditional <major>.<minor> software versioningscheme

Description This property contains a string that uniquely identifies a published revision of this In-strument Definition. This version, in conjunction with the id property, is used by AssessmentDocuments (and/or other supplementary documents) to identify which Instrument Definitionthey correspond to. The major portion of the version string should represent a generation ofthe Instrument, whereas the minor portion of the version string should represent a backwards-compatible update to the Instrument.

Example 1.2

title

Type String

Constraints Required

Description This property contains a short string that acts as a human-readable title or brief descrip-tion of the Instrument described within.

Example My Example Title

description

Type String

8 Chapter 2. Specifications

http://json.org/

http://tools.ietf.org/html/rfc3986

urn:my-organization:an-instrument-name


Description This property allows the Instrument author to explain what the Instrument is, what it’sbeing used for, or any other helpful information about the Instrument. This property is optionaland is not intended to ever be shown to an end-user.

meta

Type Metadata Collection Object

Description This property allows arbitrary information about the Instrument to be stored within thedefinition. This property is optional.

types

Type Type Collection Object

Description This property allows the Instrument author to define common data types/restrictionsthat that are used throughout the Instrument. This property is optional.

record

Type Array of Field Object

Description This property contains all data points that this Instrument is looking to collect responsesfor.

Field Object

Field Objects are the core of what makes up an Instrument Definition. They describe the data points the Instrumentwants to collect. These objects consist of several properties:

id

Type String

Constraints Required; Must be an Identifier

Description This property uniquely identifies the data point so that it can be referred to in subsequentdocuments. It must be unique within the scope of the collection it is contained within.

description

Type String

Description This property allows the Instrument author to explain what the Field is, what it’s beingused for, or any other helpful information about the Field. This property is optional and is notintended to ever be shown to an end-user.

type

Type Enumerated String or Type Object


Description This property identifies the type of data that will be returned as a response to this Field.It can be specified by either indicating the identifier of one of the Base Types, the identifier ofone of the Types defined in the Type Collection Object, or it can be a Type Object that defines aType directly within this Field.

required

Type Boolean

Description Indicates whether or not a response is required for this Field. This property is optional,and, if not specified, is assumed to be false. For recordList fields, this means that there is at

2.1. Instrument Definition Specification 9


least one non-empty response set in the list. For matrix fields, this means that at least one cellin the matrix contains a value.

annotation

Type Enumerated String

Description Indicates whether or not this Field allows for an additional text-based response thatallows the respondent to explain why they can’t or won’t provide a response for this Field. Thisproperty is optional, and, if not specified, is assumed to be none. If this Field is marked asrequired, this property cannot be any value other than none.

PossibleValues

• required - If no value for the field has been collected, an annotation must be collectedfor this Field.

• optional - An annotation may be collected for this Field.

• none - An annotation is not allowed for this Field.

explanation


Description Indicates whether or not this Field allows for an additional text-based response thatallows the respondent to provide more detail or to further explain the main response to thisField. This property is optional, and, if not specified, is assumed to be none.

PossibleValues

• required - An explanation must be collected for this Field.

• optional - An explanation may be collected for this Field.

• none - An explanation is not allowed for this Field.

identifiable

Type Boolean

Description Indicates whether or not the response for this Field will (or can) contain informationthat can be used to identify the subject or respondent. This is typically used to flag fields thatwould contain information that could be classified as “Protected Health Information” (HIPAAPHI), “Personally Identifiable Information” (NIST PII), “Personal Data” (EU Data ProtectionDirective), etc. This property is optional, and, if not specified, is assumed to be false. If arecordList or matrix field is marked as identifiable, then that means that all sub-fields are considered to be identifiable.

Type Collection Object

A Type Collection Object gives the Instrument author a means to define a set of common and/or frequently-used datatypes/restrictions that can then be referred to throughout the rest of the Instrument Definition. This object consistsof one or more properties where the property name serves as a unique identifier for the Type (in the format of anIdentifier), and the value of the property is the definition of the Type, in the format of a Type Object.

Type Object

A Type Object defines a data Type that will be used to specify the type of data that may be returned as a response to aField. Not only does it specify the base data type (e.g., text vs integer vs date), but it also allows the author toplace additional restrictions or constraints on the data.


http://www.gpo.gov/fdsys/pkg/CFR-2002-title45-vol1/pdf/CFR-2002-title45-vol1-sec164-514.pdf


http://csrc.nist.gov/publications/nistpubs/800-122/sp800-122.pdf

http://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:31995L0046



base



Description This property indicates the base Type that this Type Object will inherit its basic proper-ties from. All Types defined in an Instrument Definition must inherit from either one of the BaseTypes, or one of the Types defined in the Type Collection Object.

If this Type Object inherits from a custom Type defined in the Type Collection Object, then anyconstraints also defined in this Type Object will completely override constraints by the samename defined in the parent Type.

range

Type Bound Constraint Object

Constraints The min and max properties, if specified, must be of the same data type as the baseType this constraint is applied to (integers for integer, numeric for float, and ISO 8601-formatted strings for date/time/dateTime).

SupportedBaseTypes integer, float, date, time, dateTime

Description This property allows the definition author to set the minimum and/or maximum limits(inclusive) that a valid response would be bound by.

length

Type Bound Constraint Object

Constraints The min and max properties, if specified, must be integers. If both min and max arespecified, min must be less than or equal to max.

SupportedBaseTypes text, enumerationSet, recordList

Description For text response types, this property allows the definition author to set the minimumand/or maximum character length that the response can be. For enumerationSet responsetypes, this property allows the definition author to specify the minimum and/or maximum num-ber of enumerations the respondent can select. For recordList response types, this propertyallows the definition author to specify the minimum and/or maximum number of response setsthe respondent can provide for this Field. If this Field is also marked as required, then the min-imum value cannot be lower than one. Note that setting a min is not equivalent to marking thefield as required. This length constraint is only enforced on non-empty values.

pattern

Type String

Constraints Must be a Regular Expression as defined by ECMA 262

SupportedBaseTypes text

Description This property specifies a regular expression that the response text must match in orderto be considered a valid response.

Example ^[A-Z0-9]$

enumerations

Type Enumeration Collection Object

Constraints Required for enumeration and enumerationSet Types

SupportedBaseTypes enumeration, enumerationSet


http://en.wikipedia.org/wiki/ISO_8601

http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf


Description This property specifies the set of values that respondents are allowed to choose from.

record

Type Array of Field Object

Constraints Required for recordList Types

SupportedBaseTypes recordList

Description This property specifies the Record that respondents must respond to as a repeating set.The Fields listed in this property must be based on a simple type.

columns

Type Array of Column Object

Constraints Required for matrix Types

SupportedBaseTypes matrix

Description This property specifies the columns that make up a matrix data point. The Fields listedin this property must be based on a simple type.

rows

Type Array of Row Object

Constraints Required for matrix Types

SupportedBaseTypes matrix

Description This property specifies the rows that make up a matrix data point.

Column Object

Column Objects are to Matrices as Field are to Instruments; they define the data points that are to be collected forreach row.

id

Type String


Description This property uniquely identifies the data point so that it can be referred to in subsequentdocuments. It must be unique within the scope of the parent Field it is encapsulated in.

description

Type String

Description This property allows the Instrument author to explain what the Column is, what it’sbeing used for, or any other helpful information about the Column. This property is optional.

type

Type Enumerated String or Type Object


Description This property identifies the type of data that will be returned as a response to this Col-umn. It can be specified by either indicating the identifier of one of the simple Base Types, theidentifier of one of the Types defined in the Type Collection Object, or it can be a Type Objectthat defines a simple Type directly within this Field. Ultimately, the type must be based on asimple type.



required

Type Boolean

Description Indicates whether or not a response is required for this Column. This means that forany Row in the matrix where at least one Column is populated with a value, this Column mustalso have a value. This property is optional, and, if not specified, is assumed to be false.

identifiable

Type Boolean

Description Indicates whether or not the response for this Field will (or can) contain informationthat can be used to identify the subject or respondent. This is typically used to flag fields thatwould contain information that could be classified as “Protected Health Information” (HIPAAPHI), “Personally Identifiable Information” (NIST PII), “Personal Data” (EU Data ProtectionDirective), etc. This property is optional, and, if not specified, is assumed to be false.

Row Object

Row Objects designate the named rows that are listed in a matrix-typed field.

id

Type String


Description This property uniquely identifies the data point so that it can be referred to in subsequentdocuments. It must be unique within the scope of the parent Field it is encapsulated in.

description

Type String

Description This property allows the Instrument author to explain what the Row is, what it’s beingused for, or any other helpful information about the Row. This property is optional.

required

Type Boolean

Description Indicates whether or not a response is required for this Row. This means that at leastone column in this Row contains a value. This property is optional, and, if not specified, isassumed to be false.

Base Types

The following Types are considered part of the basic functionality provided by Instrument Definitions and can be usedwhen specifying the type of a Field, or when specifying a base when defining a new type in a Type Object.








Identi-fier

Class Description

float sim-ple

A floating-point numeric value.

integer sim-ple

An integer value.

text sim-ple

A string value.

enumer-ation

sim-ple

A string value that must be chosen from a predefined set of values.

enumer-ationSet

sim-ple

An array of one or more string values that must be chosen from a predefined set of values.

boolean sim-ple

Either a true or false value.

date sim-ple

A string value representing a date in time. Must be formatted as an ISO 8601 extended formatcalendar date (YYYY-MM-DD).

time sim-ple

A string value representing a time of day. Must be formatted as an ISO 8601 extended formattime (HH:MM:SS).

date-Time

sim-ple

A string value representing the time on a specific date. Must be formatted as an ISO 8601extended format date and time combination (YYYY-MM-DDTHH:MM:SS).

recordList com-plex

An array of multiple-response collections, where each element in the array is the same set ofsimple Fields being responded to multiple times.

matrix com-plex

A multi-value grid that presents the same simple Fields (columns) for every record (row).

Bound Constraint Object

A Bound Constraint Object is a generic structure that allows the definition author to place explicit upper and/or lowerbounds on the response of a particular Field. These objects consist of at least one of the following properties:

min

Type Dependent on context

Description This property specifies the lower bound of the constraint. This bound is inclusive,meaning that the value specified in this property is also considered a valid response. This prop-erty is optional, and, if not specified, is assumed to represent the fact that there is no lower boundother than that which makes contextual sense based on the data type and constraint involved.

max

Type Dependent on context

Description This property specifies the upper bound of the constraint. This bound is inclusive,meaning that the value specified in this property is also considered a valid response. This prop-erty is optional, and, if not specified, is assumed to represent the fact that there is no lower boundother than that which makes contextual sense based on the data type and constraint involved.

Enumeration Collection Object

An Enumeration Collection Object consists of one or more properties where the property name serves as a uniqueidentifier for the enumeration, and the value of the property is the definition of the enumeration, in the format of aEnumeration Object (or null).

This identifier is a string that adheres to the following restrictions:






• Consists of 1 or more of the following characters:

– Lowercase latin alphabetic characters (“a” through “z”; Unicode 0061 through 007A)

– Latin numeric digits (“0” through “9”; Unicode 0030 through 0039)

– Underscore characters (“_”; Unicode 005F)

– Hyphen characters (“-“; Unicode 002D)

• The last character is a lowercase latin alphabetic character or latin numeric digit.

• Does not contain consecutive underscore and/or hyphen characters.

The unique identifiers for these enumerations are used by Assessment Documents (and/or other supplementary docu-ments) to indicate which enumeration(s) were selected by the respondent.

Example Identifiers:

• blue_green

• abc123

• ref-1-2-alpha

• 42

• a

Enumeration Object

An Enumeration Object represents one possible response a respondent has available to them in the context of a Fieldthat is of the type enumeration or enumerationSet. These object consist of the following properties:

description

Type String

Description This property allows the Instrument author to explain what the Enumeration is, whatit’s being used for, or any other helpful information about the Enumeration. This property isoptional.

Identifier

Identifiers are strings that adhere to the following restrictions:





• The first character is an alphabetic character.

• The last character is not an underscore.

• Does not contain consecutive underscore characters.


• page1

• grp_a



• ref_1_2_alpha

Metadata Collection Object

A Metadata Collection Object consists of one to many properties that allows you to attach arbitrary, implementation-specific, or other such data to structures within an Instrument Definition.

For consistency’s and interoperability’s sake, some common data elements are defined below, but note that the Meta-data Collection Object has no required or predefined properties, and can therefore contain any (legal JSON) propertynames and value data types. Software that consumes Instrument Definitions must ignore any property whose name itdoes not recognize or support.

Prop-ertyName

DataType

Example Description

author String John Smith A string that describes the entity that created this definition.copy-right

String 2009, SmithInstrumenta-tion

A string that describes who owns the copyright to the Instrument implementedby this definition.

home-page

String http://www.example.com

A URL (as described by RFC1738) to a web page that has more informationabout this Instrument.

genera-tor

String Survey-Builder/1.0

A string that indicates what application produced the Instrument Definition.This must should be formatted similarly to HTTP Product Token strings as spec-ified in RFC2616.

2.2 Calculation Set Definition Specification

Table of Contents

• Calculation Set Definition Specification

– Overview

– Format

– Structure

* Root Object

* Instrument Reference Object

* Calculation Object

* Identifier


– Calculation Methods

* python

· Expressions

· Callables


http://www.example.com




http://tools.ietf.org/html/rfc2616#section-3.8


· Assessment Variable

· Previous Calculation Variable

* htsql

· Assessment Parameters

· Previous Calculation Parameters

– Calculation Results

2.2.1 Overview

A RIOS Calculation Set Definition is a standard means to represent a set of calculations that can be applied to the datacollected in an Assessment Document for a given Instrument Definition.

2.2.2 Format

Calculation Set Definitions are stored and exchanged as JSON (JavaScript Object Notation) objects. The structureof these objects must adhere to the rules set forth in this document. When stored in files, these files must be UTF-8encoded.

2.2.3 Structure

Root Object

The Root Object of a Calculation Set Definition consists of a few properties:

instrument

Type Instrument Reference Object


Description This property specifies which Instrument Definition the calculations defined within thisdefinition applies to.

meta


Description This property allows arbitrary information about this Calculation Set to be stored withinthe definition. This property is optional.

calculations

Type Array of Calculation Object

Constraints Required; Must contain at least one Calculation Object

Description This property contains the set of calculations that should be applied to an AssessmentDocument. The ordering of calculations in this array is important, as they are always executedin the specified order.

2.2. Calculation Set Definition Specification 17

http://json.org/


Instrument Reference Object

An Instrument Reference Object is the means for a Calculation Set Definition to reference the exact Instrument (andversion of that Instrument) that the values contained within are in reference to.

id

Type String


Description This property is a reference to the id property on the root object of an Instrument Defi-nition. It is meant to specify the exact Instrument this Calculation Set is augmenting.

version

Type String


Description This property is a reference the the version property on the root object of an InstrumentDefinition. It is meant to specify the exact revision of the Instrument this Calculation Set isaugmenting.

Calculation Object

Calculation Objects are the core of what makes up a Calculation Set Definition. They describe the values that shouldbe calculated for an Assessment Document. These objects consist of several properties:

id

Type String


Description This property uniquely identifies the calculation so that its value can be referred to insubsequent documents or calculations. It must be unique amongst all calculations and fields IDsfrom the original Instrument Definition.

description

Type String

Description This property allows the Calculation Set author to explain what the calculation is, whatit’s being used for, or any other helpful information. This property is optional and is not intendedto ever be shown to an end-user.

identifiable

Type Boolean

Description Indicates whether or not the value generated by this calculation will (or can) containinformation that can be used to identify the subject or respondent. This is typically used toflag calculations that would contain information that could be classified as “Protected HealthInformation” (HIPAA PHI), “Personally Identifiable Information” (NIST PII), “Personal Data”(EU Data Protection Directive), etc. This property is optional, and, if not specified, is assumedto be false.

type


Constraints Required; Must be one of the Instrument Definition data types listed below







Description This property identifies the type of data that will be returned as a response to this Field.

PossibleValues

• float

• integer

• text

• boolean

• date

• time

• dateTime

method



Description This property identifies method that will be used to perform the calculations.

PossibleValues

MethodDescriptionpython The calculation will be in the form of a single-line Python v2.7 expression, or the

name of a Python callable that can be imported and executed.htsql The calculation will be in the form of an HTSQL v2 expression.

options

Type Object

Constraints The contents of the Object depend on the method specified in the method property.See the Calculation Methods section for information on which options are needed for whichmethods.

Description This property allows the calculation author to provide the necessary information to thecalculation engine in order to perform the operation.

Identifier










• page1



• grp_a

• ref_1_2_alpha


A Metadata Collection Object consists of one to many properties that allows you to attach arbitrary, implementation-specific, or other such data to structures within an Calculation Set Definition.

For consistency’s and interoperability’s sake, some common data elements are defined below, but note that the Meta-data Collection Object has no required or predefined properties, and can therefore contain any (legal JSON) propertynames and value data types. Software that consumes Calculation Set Definitions must ignore any property whose nameit does not recognize or support.

Prop-ertyName

DataType

Example Description

author String John Smith A string that describes the entity that created this definition.copy-right

String 2009, SmithInstrumen-tation

A string that describes who owns the copyright to the Instrument, Calculations,or Scores implemented by this definition.

home-page


A URL (as described by RFC1738) to a web page that has more informationabout this Instrument or Calculation.

genera-tor


A string that indicates what application produced the Calculation Set Defini-tion. This must should be formatted similarly to HTTP Product Token strings asspecified in RFC2616.

2.2.4 Calculation Methods

python

The python method provides two approaches to specify the calculation, both being implemented using the Pythonv2.7 language. The approach used is based on which properties are passed into the accompanying options object.

Expressions

The first approach is through an explicitly defined expression. In the options object that accompanies the calculationdefinition, there must be a property named expression that contains a single-line Python expression. The valuethat results from the evaluation of this expression is what will be stored as the result of the calculation.

This expression will be evaluated within a scope that includes:

• The cmath module

• The datetime module

• The math module

• The re module

• A assessment variable that contains the Assessment values (described in Assessment Variable)

• A calculations variable that contains the previously calculation values (described in Previous CalculationVariable)







https://docs.python.org/2.7/reference/index.html

https://docs.python.org/2.7/reference/index.html

https://docs.python.org/2/library/cmath.html

https://docs.python.org/2/library/datetime.html

https://docs.python.org/2/library/math.html

https://docs.python.org/2/library/re.html


Given an Instrument that defines two fields, “foo” and “bar”, the following are some examples of what expressionscould look like:

assessment['foo'] * 2

assessment['foo'] + math.log(assessment['foo'])

'GOOD' if re.match(r'^[a-z]{3}$', assessment['bar']) else 'BAD'

Callables

The second approach is through specifying a callable object by name. In the options object that accompanies thecalculation definition, there must be a property named callable that contains the dot-separated, fully-qualified pathto the callable. The value that this callable returns is what will be stored as the result of the calculation.

When executed, the callable object will receive the following arguments:

assessment A dictionary containing the Assessment values (described in Assessment Variable).

calculations A dictionary contain the previous calculation values (described in Previous Calculation Variable).

If the callable property had the value “mymodule.my_calculation”, it could be implemented as follows:

# mymodule.py

def my_calculation(assessment, calculations):return assessment['foo'] * 2

Or,

# mymodule.py

class Calculator(object):def __call__(self, assessment, calculations):

return assessment['foo'] * 2

my_calculation = Calculator()

Assessment Variable

In both execution approaches, a variable named assessment is made available that contains the values from theAssessment. This variable is a dictionary whose keys correspond to the field identifiers from the Instrument. All fieldidentifiers will be present as keys, even if there is no value (e.g., None) recorded for the field.

The values for these keys will be coerced to the appropriate Python types according to the following table:



InstrumentType

Python Type

integer intfloat floattext unicodeboolean booldate datetime.datetime datetime.timedateTime datetime.datetimeenumeration unicodeenumera-tionSet

list of unicode

recordList list of dictionaries whose keys are the sub-field identifiersmatrix dictionary whose keys are the row identifiers, and the values are then dictionaries whose keys are

the column identifiers

Previous Calculation Variable

In both execution approaches, a variable named calculations is made available that contains the values thatresulted from previous calculations performed during this execution. Calculations within a given Calculation Setare executed in the order they’re listed in the definition. The resulting values are then passed to each subsequentcalculation.

For example, imagine a Calculation Set definition where three calculations are defined in the following order: “foo”,“bar”, “baz”. When the “foo” calculation is executed, the calculations dictionary will be empty. When the “bar”calculation is executed, the calculations dictionary will have a single key, “foo”, with the results of the “foo”calculation. When the “baz” calculation is executed, the calculations dictionary will have two keys, “foo” and“bar”, containing their respective calculation results.

htsql

The htsql method allows calculations to be written as HTSQL v2 expressions. The expression to execute must bespecified in an expression property on the accompanying options object.

Given an instrument that defines two fields, “foo” and “bar”, the following are some examples of what expressionscould look like:

$foo * 2

trunc($foo) + 42

if($bar > 10, 'GOOD', 'BAD')

{$foo + $bar}

/{($bar - $foo) / $foo}

If the value returned by the HTSQL expression is scalar, that value is what is kept as the result. If the value returned isa Record, then the value in the first column of that Record is kept as the result. If the value return is a list of Records,then the value in the first column of the first Record is kept as the result.


http://htsql.org/doc/


Assessment Parameters

Assessment values for simple-typed fields will be available to your expression as parameters that can be accessed usingreference syntax (e.g., prefixing the name with $ – so, the “foo” field would be access liked $foo).

To access the values of matrix cells, you’ll need to concatenate the ID of the matrix field with the ID of the row andthe ID of the column with underscores. For example, $matrixfield_firstrow_somecolumn.

Due to a limitation of the the mechanics of HTSQL, the values for the subfields in recordList questions will not beavailable for use by your expressions.

The values for these parameters will be coerced to the appropriate HTSQL types according to the following table:

Instrument Type HTSQL Typeinteger integerfloat floattext untypedboolean booleandate datetime timedateTime datetimeenumeration untypedenumerationSet record of untyped

Previous Calculation Parameters

Much like the Assessment values, the values that resulted from previous calculations performed during this executionwill be available as referenceable ($-prefixed) parameters. Calculations within a given Calculation Set are executed inthe order they’re listed in the definition. The resulting values are then passed to each subsequent calculation.

2.2.5 Calculation Results

The results of the calculations in a Calculation Set will be stored in the document-level meta structure of the As-sessment Document under the property named calculations. This property will be an object whose keys are theidentifiers of the calculations, and whose values are the results of those calculations. All calculation identifiers mustbe present in the object, even those whose calculations resulted in a null/None.

2.3 Assessment Document Specification

Table of Contents

• Assessment Document Specification

– Overview

– Format

– Structure

* Root Object


2.3. Assessment Document Specification 23


* Value Collection Object

* Value Object

* Value Collection Mapping


2.3.1 Overview

A RIOS Assessment Document is a standard means to represent a set of values that fulfill the requirements describedin a corresponding Instrument Definition.

2.3.2 Format

Assessment Documents are stored and exchanged as JSON (JavaScript Object Notation) objects. The structure ofthese objects must adhere to the rules set forth in this document. When stored in files, these files must be UTF-8encoded.

2.3.3 Structure

Root Object

The Root Object of an Assessment Document consists of several properties:

instrument



Description This property specifies which Instrument Definition the values contained within thisAssessment Document correspond to.

meta


Description This property allows arbitrary information about the Assessment to be stored within thedocument. This property is optional.

values

Type Value Collection Object


Description This property contains the values for the Fields defined in the associated InstrumentDefinition.


An Instrument Reference Object is the means for an Assessment Document to reference the exact Instrument (andversion of that Instrument) that the values contained within are in reference to.

id


http://json.org/


Type String


Description This property is a reference to the id property on the root object of an Instrument Def-inition. It is meant to specify the exact Instrument this Assessment Document is in responseto.

version

Type String


Description This property is a reference the the version property on the root object of an InstrumentDefinition. It is meant to specify the exact revision of the Instrument this Assessment Documentis in response to.

Value Collection Object

A Value Collection Object consists of one to many properties where the property name serves as a reference to theID of a Field defined in the associated Instrument, and the value of that property is a Value Object which contains theactual value for the Field.

This object must contain a property for every Field Object defined in the corresponding Field Collection Object in theInstrument Definition.

Value Object

A Value Object contains a value for a Field on an Instrument.

value


Description This property contains the main value for the Field. If there is no value for theField, the value for this property should be null. This non-response indication should be usedfor all data types (e.g., don’t use an empty string for text data types, or empty arrays forenumerationSet or recordList data types).

Type Dependent on the type defined by the corresponding Field Object in the Instrument Definition.See following table:

2.3. Assessment Document Specification 25



FieldDataType

JSON Data Type Constraints

integer Number Must be an integer (no decimal points or fractional num-bers)

float Numbertext Stringboolean Booleandate String Must be an ISO 8601 extended format calendar date

(YYYY-MM-DD)time String Must be an ISO 8601 extended format time (HH:MM:SS)dateTime String Must be an ISO 8601 extended format date and time com-

bination (YYYY-MM-DDTHH:MM:SS)enumera-tion

String

enumera-tionSet

Array of Strings

recordList Array of ValueCollection Object

matrix Value CollectionMapping

explanation

Type String

Description This property contains the additional explanation text for a response, if any was pro-vided.

annotation

Type String

Description This property contains the additional annotation text for a response, if any was pro-vided.

meta


Description This property allows arbitrary information about the value to be stored within the doc-ument. This property is optional.

Value Collection Mapping

A Value Collection Mapping consists of one to many properties where the property name serves as a reference to theID of a Row Object defined in the associated Matrix Field, and the value of that property is a Value Collection Objectwhich contains the value(s) for the associated Column Objects.

This object must contain a property for every Row Object defined in the corresponding Matrix Field Object in theInstrument Definition. The embedded Value Collection Objects must contain a property for every Column Objectfrom the corresponding Matrix Field Object.







A Metadata Collection Object consists of one to many properties that allows you to attach arbitrary, implementation-specific, or other such data to structures within an Assessment Document.

For consistency’s and interoperability’s sake, some common data elements are defined below, but note that the Meta-data Collection Object has no required or predefined properties, and can therefore contain any (legal JSON) propertynames and value data types. Software that consumes Assessment Documents must ignore any property whose name itdoes not recognize or support.

Prop-ertyName

Docu-mentScope

DataType

Exam-ple

Description

lan-guage

Assess-ment

String en A Language Tag (as described in RFC5646) that indicates the lan-guage/locale used in the values of the Assessment.

appli-cation

Assess-ment

String Survey-Mas-ter/1.0

A string that indicates what application produced the Assessment Docu-ment. This must should be formatted similarly to HTTP Product Tokenstrings as specified in RFC2616.

date-Com-pleted

Assess-ment

String 2012-11-20T10:46:08

An ISO 8601 extended format date and time combination that indicateswhen data collection for the Assessment completed.

timeTakenAssess-ment,Value

Num-ber

23500 An integer that indicates the number of milliseconds that completion ofthe scoped object took. E.g., it took 23500 seconds for the respondent toprovide the value for a particular Field.

calcu-lations

Assess-ment

Ob-ject

An object that contains the results from executing the calculations definedin the corresponding Calculation Set Definition.

2.4 Web Form Configuration Specification

Table of Contents

• Web Form Configuration Specification

– Overview

– Format

– Structure

* Root Object


* Page Object

* Element Object

* Question Object

* Descriptor Object

* Event Object

* Widget Configuration Object

* Audio Source Object

2.4. Web Form Configuration Specification 27





* Parameter Collection Object

* Parameter Object

* Localized String Object

* Identifier

* Compound Identifier

– Text Formatting and Parameters


2.4.1 Overview

A RIOS Web Form Configuration is a standard means to augment an Instrument Definition with additional configura-tion and meta-data that allows the Instrument to be administered via a web-based application.

2.4.2 Format

Web Form Configurations are stored and exchanged as JSON (JavaScript Object Notation) objects. The structure ofthese objects must adhere to the rules set forth in this document. When stored in files, these files must be UTF-8encoded.

2.4.3 Structure

Root Object

The Root Object of a Web Form Configuration consists of several properties:

instrument



Description This property specifies which Instrument Definition the Form is based on.

meta


Description This property allows arbitrary information about this Web Form to be stored within theconfiguration. This property is optional.

defaultLocalization

Type String; Must be in the form of a RFC5646 Language Tag


Description This property specifies the localization that will be available in every Localized StringObject within the Form Configuration.

title

Type Localized String Object


http://json.org/



Description This property contains a short string that acts as a human-readable title or brief descrip-tion of the Form described within.

Example My Example Title

pages

Type Array of Page Object

Contraints Required; Must contain at least one Page Object

Description This property lists the Pages of Questions (and/or other Elements) that the Form ismade up of. The order that the Pages are placed in this property is the same order that they willbe presented on the front end.

parameters

Type Parameter Collection Object

Description This property specifies the identifiers of variables that will be provided upon instantia-tion by a source external to this Form.


An Instrument Reference Object is the means for a Web Form Configuration to reference the exact Instrument (andversion of that Instrument) that the responses contained within are in reference to.

id

Type String


Description This property is a reference to the id property on the root object of an InstrumentDefinition. It is meant to specify the exact Instrument this Web Form Configuration is based on.

version

Type String


Description This property is a reference the the version property on the root object of an Instru-ment Definition. It is meant to specify the exact revision of the Instrument this Form Configura-tion is based on.

Page Object

A Page object represents a all the Elements of a Form that will be shown on a single screen. It consists of severalproperties:

id

Type Identifier


Description This property specifies a unique identifier for the Page, so that it can be referenced inthe context of event trigger expressions.

elements

Type Array of Element Object




Constraints Required; Must contain at least one Element Object

Description This property contains the list of Elements (Questions, text entries, dividers, etc) thatthe Page is made up of. The order that the Elements are placed in this property is the same orderthat they will be presented on the front end.

Element Object

An Element object represents a single piece of a Form. It consists of several properties:

type



Description This property indicates the type of element that is being described.

PossibleValues

Name Descriptionquestion A Question that the user can respond to.header A header/title text entry. Analogous to an H1 HTML tag.text A paragraph or group of text that should be displayed to the user.divider A horizontal screen divider. Analogous to an HR HTML tag.audio An audio recording exposed via a simple player.

options

Type Object

Description This property is a container for whatever additional parameters are needed for thisparticular Element.

PossibleValues

ElementType

Applicable Options

question The options are in the form of a Question Object.header The only option allowed is a single property named text that is a Localized

String Object. This property can be marked up.text The only option allowed is a single property named text that is a Localized

String Object. This property can be marked up.divider N/Aaudio The only option allowed is a single property named source that is an Audio

Source Object.

tags

Type Array of Identifier

Description This property allows the Form author to tag the element as belonging to a particular“group” so that they may be later referenced in an Event Object target as collection. These tagscannot be the same as the IDs of any Fields in the associated Instrument Definition, nor the idof any Pages.



Question Object

A Question Object defines how a Field from an Instrument is presented to the user so that they may provide a response.

fieldId

Type String


Description This property is a reference to the ID of a Field that is defined in the associated Instru-ment Definition. A Field ID can only be used in one Question Object in a given Form.

text



Description This property allows the Form author to provide a more detailed description for theQuestion. Often, it is an explicit question that is being asked of the Subject. This text can bemarked up.

Example What is the your age?

audio

Type Audio Source Object

Description This property allows the Form author to supply audio recordings of the (or in supportof) the question that the end user can play. This property is optional.

help


Description This property allows the Form author to supply additional text that will be provided ashelp content for the Question. This property is optional and can contain marked up text.

error


Description This property allows the Form author to supply text that will be presented to the userwhen the value they’ve input is not valid. This property is optional and can contain marked uptext.

enumerations

Type Array of Descriptor Object

Constraints Only applies to Questions for Fields of type enumeration or enumerationSet

Description This property contains the list of Enumerations that are presented to the user for themto choose from. The order that the Enumeration Objects are placed in this property is the sameorder that they will be presented on the front end. Only the enumerations specified in thisproperty will be displayed to the user. If this property is not specified, then all enumerations willbe displayed using their IDs.

questions

Type Array of Question Object

Constraints Required for Fields of type recordList or matrix



Description This property allows the author to specify the sequence and configuration of the childFields contained within a recordList or matrix Field. For matrices, these questions corre-spond to the columns.

rows


Constraints Required for Fields of type matrix

Description This property allows the author to specify the sequence and configuration of the rowsin a matrix field.

widget

Type Widget Configuration Object

Description This property allows the Form author to override or provide additional configurationoptions to the front-end widget that will be used to collect the response from the user. Thisproperty is optional, and, if not specified, will result in the default widget to be used for the datatype of the Field.

events

Type Array of Event Object

Description This property allows for the configuration of different events or actions to occur to theQuestion based on satisfying the specified expressions. This property is optional and has nodefault value.

Descriptor Object

A Descriptor Object is the means with which an author defines the text of simple facets of a Form such as Enumerationsand Matrix Rows.

id

Type String


Description This property is a reference to the ID of an Enumeration or Row on the Field that isdefined in the associated Instrument Definition.

text



Description This property allows the Form author to provide a more detailed description for theEnumeration/Row rather than displaying a code. This text can be marked up.

audio

Type Audio Source Object

Description This property allows the Form author to supply audio recordings of the (or in supportof) the Enumeration/Row that the end user can play. This property is optional.

help




Description This property allows the Form author to supply additional text that will be provided ashelp content for the Enumeration/Row. This property is optional and can contain marked up text.

Event Object

An Event Object represents an action that the Form will take when a particular condition is met. This object consistsof the following properties:

trigger

Type String Instrument Definition


Description This property specifies a REXL expression that, when it evaluates to a truthy value, willthen cause the action specified in this Event Object to execute.

action



Description This property indicates which action the front-end application should take when thecorresponding expression evaluates to a truthy value.

PossibleValues

Ac-tion

ApplicableElements

Ap-pliestoPages

Description

hide question,header, text,divider, audio

Yes Completely hides the element from the user.

dis-able

question,header, text,divider, audio

Yes Shows the element to the user, but does not allow themto interact with or respond to it.

hideEnu-mera-tion

question No Hides the specified enumerations (in enumerationand enumerationSet Questions) from the user.

fail question No Causes the response to the Question to be considered“invalid”, meaning the user must change it before theycan successfully complete the Form.

targets

Type Array of Compound Identifier

Description This property specifies which Element(s) are impacted by the action being executed.These Identifiers can either be either references to the fieldId of Questions, the id of Pages,or a tag specified by one or more Elements in the tags property. If not specified, it is impliedthat the action applies to the Question the Event is associated with.

options

Type Object

Constraints The contents of the Object depend on the action specified.



Descriptions This property allows the Form author to provide configuration parameters to theaction being executed. This property is optional.

PossibleValues

Option ApplicableActions

Description

text fail A Localized String Object that contains the error message toshow on the target question. Required.

enumer-ations

hideEnumer-ation

A list of enumeration IDs to hide on the target question. Re-quired.

Widget Configuration Object

A Widget Configuration Object is the means to specify which front-end data collection component should be used andto provide configuration parameters for that component. This object consists of a couple properties:

type



Description This property indicates the type of the front-end widget that should be used. The fol-lowing listed widgets are considered the “default” set and must be recognized by any consumerof the Web Form. Custom and/or implementation-specific widget types are allowed to be used.If a consumer of a Web Form encounters a widget type it does not recognize, it must default tousing the widgets indicated below.

PossibleValues

Type ApplicableField Types

Description

input-Text

text* A single-line text box.

input-Number

integer*,float*

A single-line text box optimized for numeric input.

textArea text A multi-line text box.radio-Group

enumeration*,boolean*

A group of radio button options that only allows one selection.

check-Group

enumera-tionSet*

A group of checkbox options that allows multiple selections.

drop-Down

enumeration,boolean

A drop-down selection box that only allows one selection.

datePicker date* TBDtimePicker time* TBDdate-TimePicker

dateTime* TBD

recordList recordList* A complex widget that allows the editing of repeated sets ofquestions in a vertically-scrolling fashion.

matrix matrix* A grid of Fields where the Questions are presented horizon-tally and repeated for each row in the matrix.

Field types notated with a * use that widget by default.



options

Type Object

Constraints The contents of the Object depend on the widget specified in the type property.

Descriptions This property allows the Form author to provide configuration parameters to the widgetbeing used. This property is optional. The base options for the “default” widget set are listedbelow. If a consumer of a Web Form encounters an option it does not recognize, it must beignored.

PossibleValues

Op-tion

Appli-cableWid-gets

De-fault

Description

width input-Text,input-Num-ber,textArea

mediumSpecifies the width of the widget. Allows small, medium, orlarge.

height textArea mediumSpecifies the height of the widget. Allows small, medium, orlarge.

add-La-bel

recordList Add A Localized String Object that specifies the text to use on the buttonthat adds a new record to the list.

re-move-La-bel

recordList Re-move

A Localized String Object that specifies the text to use on the buttonthat removes a record from the list.

hotkeysradio-Group,check-Group

A mapping of Enumeration IDs to the numeric digits that will act ashotkeys to select the enumeration via keyboard entry. This option isignored if there are more than 10 enumerations. If an enumerationis not listed in the mapping, it will automatically be assigned one.

au-to-Hotkeys

radio-Group,check-Group

false A boolean that indicates that hotkeys must be enabled, even if thehotkeys option is not specified.

ori-en-ta-tion

radio-Group,check-Group

ver-ti-cal

Specifies the direction that the enumerations should be listed. Al-lows vertical or horizontal.

Audio Source Object

An Audio Source Object is a container that allows the configuration author to specify the source files to play incomponents that provide audio playback functionality. It is structured much like a Localized String Object, whereeach property is a RFC5646 Language Tag. The value of each property is an array of strings that contain URLs to thefiles for each locale. Each URL in the array should point to a file that has the same recording, but a different encoding(e.g., MP3 vs. OGG vs. WAV).

Example:




{"en": [

"http://example.com/foo.mp3","http://example.com/foo.wav"

],"fr": [

"http://example.com/foo-fr.mp3"]

}

Note: The URLs for the audio files can technically be path-relative, domain-relative, or fully-qualified. It is advised,though, that you only use fully-qualified (e.g., http://example.com/foo.mp3) or domain-relative (e.g., /somewhere/foo.mp3). Using path-relative URLs (e.g, ../../foo.mp3) can be troublesome to configure inenvironments where subpaths or mount points may not be predictable or stable.

Parameter Collection Object

A Parameter Collection object consists of one-to-many properties where the property name serves as a reference to avariable that will be supplied to the Form rendering engine from an external source. These variables can be used inany event logic, and can be substituted into the text of any element that renders text. The keys to this object must be inthe form of an Identifier. The values in this object must be in the form of a Parameter Object.

Parameter Object

A Parameter object describes the nature of the incoming parameter. It consists of the following properties:

type


Contraints Required

Description This property indicates the rough data type of the value that will be received in thisvariable.

PossibleValues numeric, text, boolean

Localized String Object

A Localized String Object is a generic container that allows the configuration author to provide text for use in a Formthat is accompanied with localized (translated) versions of that text. This object contains one or more properties, whereeach property is a RFC5646 Language Tag. The values of all the properties are the localized versions of the same text.

Example:

{"en": "What is the subject's age?","fr": "Quel est l'âge de l'objet?"

}

Every Localized String Object within a given Web Form Configuration must contain at least one property that is keyedwith the same Language Tag that is defined in the defaultLocalization property of the Root Object. This ensures thatthe application responsible for displaying the Form can be guaranteed to always have at least one known text stringavailable to it.




Identifier










• page1

• grp_a

• ref_1_2_alpha

Compound Identifier

Compound Identifiers are strings that are combinations of Identifier strings that are joined by a single period character(Unicode 002E).


• page1

• foo.bar

• grp_a.f00.blah

2.4.4 Text Formatting and Parameters

In numerous places throughout this document, there are properties that contain text that is displayed to the user undervarying conditions. When one of these properties is noted as allowing “marked up” text, this means that the propertysupports two pieces of functionality:

• You can use the Creole markup language to add simple formatting to the text, such as bold/italic font decorations,links, line breaks, etc. The syntax for performing this can be found here.

• You can perform parameter substitution to have the values of various parameters be inserted into your text.This is done by using the following notation:

How old is <<Parameter subject_name>>?

or:

How old is <<Parameter subject_name this subject>>?

The first token after the Parameter keyword is the name of the parameter to insert into the text. If theparameter does not exist or is null, then the token(s) after the parameter name are inserted into the text. Ifnothing is listed after the parameter name, then nothing is inserted.

If subject_name was set to “Jason” then the two examples would both look like:


http://www.wikicreole.org

http://www.wikicreole.org/wiki/Creole1.0


How old is Jason?

If subject_name was not available for the Form to use, then the first example would look like:

How old is?

And the second example would look like:

How old is this subject?


A Metadata Collection Object consists of one to many properties that allows you to attach arbitrary, implementation-specific, or other such data to structures within a Web Form Configuration.

For consistency’s and interoperability’s sake, some common data elements are defined below, but note that the Meta-data Collection Object has no required or predefined properties, and can therefore contain any (legal JSON) propertynames and value data types. Software that consumes Web Form Configurations must ignore any property whose nameit does not recognize or support.

Prop-ertyName

DataType

Example Description

author String John Smith A string that describes the entity that created this configuration.copy-right


A string that describes who owns the copyright to the Instrument or Form im-plemented by this configuration.

home-page


A URL (as described by RFC1738) to a web page that has more informationabout this Instrument or Form.

genera-tor


A string that indicates what application produced the Form Configuration. Thismust should be formatted similarly to HTTP Product Token strings as specifiedin RFC2616.

2.5 SMS Interaction Configuration Specification

Table of Contents

• SMS Interaction Configuration Specification

– Overview

– Format

– Structure

* Root Object


* Timeout Object

* Timeout Details Object








* Step Object

* Question Object

* Descriptor Object

* Localized String Object

* Identifier


2.5.1 Overview

A RIOS SMS Interaction Configuration is a standard means to augment an Instrument Definition with additionalconfiguration and meta-data that allows the Instrument to be administered via an SMS text message-based application.

2.5.2 Format

SMS Interaction Configurations are stored and exchanged as JSON (JavaScript Object Notation) objects. The structureof these objects must adhere to the rules set forth in this document. When stored in files, these files must be UTF-8encoded.

2.5.3 Structure

Root Object

The Root Object of an SMS Interaction Configuration consists of several properties:

instrument



Description This property specifies which Instrument Definition the Interaction is based on.

meta


Description This property allows arbitrary information about the Interaction to be stored within theconfiguration. This property is optional.

defaultLocalization

Type String; Must be in the form of a RFC5646 Language Tag


Description This property specifies the localization that will be available in every Localized StringObject within the Interaction Configuration.

defaultTimeout

Type Timeout Object

Description This property specifies what the timeout behavior is for the Interaction.

steps

2.5. SMS Interaction Configuration Specification 39

http://json.org/



Type Array of Step Object

Contraints Required; Must contain at least one Step Object

Description This property lists the Steps of Questions (and/or other Steps) that the Interaction ismade up of. The order that the Steps are placed in this property is the same order that they willbe executed.


An Instrument Reference Object is the means for an SMS Interaction Configuration to reference the exact Instrument(and version of that Instrument) that the responses contained within are in reference to.

id

Type String


Description This property is a reference to the id property on the root object of an InstrumentDefinition. It is meant to specify the exact Instrument this SMS Interaction Configuration isbased on.

version

Type String


Description This property is a reference the the version property on the root object of an In-strument Definition. It is meant to specify the exact revision of the Instrument this InteractionConfiguration is based on.

Timeout Object

A Timeout object describes what to do when a user doesn’t respond for a period of time. It must contain at least oneof the following properties:

warn

Type Timeout Details Object

Description This property describes the warning phase of a timeout. When the specified thresholdis met, a message is sent to the user to warn them about their impending timeout.

abort

Type Timeout Details Object

Description This property describes the final phase of a timeout. When the specified threshold ismet, a message is sent to the user telling them that the Interaction is being aborted, and thesystem stops processing any further steps in the Interaction.

Timeout Details Object

theshold

Type Integer





Description The number of seconds of idle time since the last action was performed.

text



Description The message to send when this timeout event occurs.

Step Object

A Step object represents a single piece of an Interaction. It consists of several properties:

type



Description This property indicates the type of step that is being described.

PossibleValues

Name Descriptionquestion A Question that the user can respond to.text Some text that should be sent to the user.

options

Type Object

Description This property is a container for whatever additional parameters are needed for thisparticular Step.

PossibleValues

StepType

Applicable Options

ques-tion

The options are in the form of a Question Object.

text The only option allowed is a single property named text that is a Localized StringObject. This property can be marked up.

Question Object

A Question Object defines how a Field from an Instrument Definition is presented to the user so that they may providea response.

fieldId

Type String


Description This property is a reference to the ID of a Field that is defined in the associated In-strument Definition. A Field ID can only be used in one Question Object in a given Interaction.Interaction Questions can only represent Instrument Fields that are based on Simple Instrumentdata types.



text



Description This property allows the Interaction author to provide a more detailed description forthe Question. Often, it is an explicit question that is being asked of the Subject.

Example What is the your age?

error


Description This property allows the Interaction author to supply text that will be presented to theuser when the value they’ve input is not valid. This property is optional.

enumerations


Constraints Only applies to Questions for Fields of type enumeration or enumerationSet

Description This property contains the list of Enumerations that are presented to the user for themto choose from. The order that the Enumeration Objects are placed in this property is the sameorder that they will be presented on the front end.

Descriptor Object

A Descriptor Object is the means with which an author defines the text of simple facets of an Interaction such asEnumerations.

id

Type String


Description This property is a reference to the ID of an Enumeration or Row on the Field that isdefined in the associated Instrument Definition.

text



Description This property allows the Interaction author to provide a more detailed description forthe Enumeration rather than displaying a code. This text can be marked up.

Localized String Object

A Localized String Object is a generic container that allows the configuration author to provide text for use in aInteraction that is accompanied with localized (translated) versions of that text. This object contains one or moreproperties, where each property is a RFC5646 Language Tag. The values of all the properties are the localized versionsof the same text.

Example:




{"en": "What is the subject's age?","fr": "Quel est l'âge de l'objet?"

}

Every Localized String Object within a given SMS Interaction Configuration must contain at least one property that iskeyed with the same Language Tag that is defined in the defaultLocalization property of the Root Object. This ensuresthat the application responsible for displaying the Interaction can be guaranteed to always have at least one known textstring available to it.

Identifier










• page1

• grp_a

• ref_1_2_alpha


A Metadata Collection Object consists of one to many properties that allows you to attach arbitrary, implementation-specific, or other such data to structures within an SMS Interaction Configuration.

For consistency’s and interoperability’s sake, some common data elements are defined below, but note that the Meta-data Collection Object has no required or predefined properties, and can therefore contain any (legal JSON) propertynames and value data types. Software that consumes SMS Interaction Configurations must ignore any property whosename it does not recognize or support.



Prop-ertyName

DataType

Example Description

author String John Smith A string that describes the entity that created this configuration.copy-right


A string that describes who owns the copyright to the Instrument or Interactionimplemented by this definition.

home-page


A URL (as described by RFC1738) to a web page that has more informationabout this Instrument or Interaction.

genera-tor


A string that indicates what application produced the Interaction Configuration.This must should be formatted similarly to HTTP Product Token strings as spec-ified in RFC2616.

2.6 REXL - RIOS Expression Language Specification

Table of Contents

• REXL - RIOS Expression Language Specification

– Overview

– Syntax

2.6.1 Overview

The RIOS Expression Language (REXL) is a lightweight expression syntax that is used in various places in the RIOSspecifications to allow configuration authors to implement logical- or calculation-based functionality.

2.6.2 Syntax

TBD







CHAPTER 3

Examples

3.1 Example of a Simple Definition Set

Table of Contents

• Example of a Simple Definition Set

– Overview

– Instrument

– Calculation Set

– Web Form

– SMS Interaction

– Assessment

3.1.1 Overview

The following examples illustrate a very simple Instrument and its accompanying configurations. The Instrumentdefines two fields to be collected. There is a Calculation Set definition that provides some post-Assessment calculationsto perform on the Assessment data. There are examples of how this Instrument can be represented in both a Web Formand an SMS Interaction. Finally, there is an example Assessment that could result from this Instrument.

It is not required to produce a full suite of configurations for every Instrument; this is only an example of what ispossible.

45


3.1.2 Instrument

{"id": "urn:examples:simple","version": "1.0",

"title": "A Simple Example",

"record": [{

"id": "name","type": "text","required": true

},

{"id": "birthdate","type": "date"

}]

}

3.1.3 Calculation Set

{"instrument": {"id": "urn:examples:simple","version": "1.0"

},

"calculations": [{

"id": "uppercase_name","type": "text","method": "python","options": {

"expression": "assessment['name'].upper()"}

},

{"id": "birth_year","type": "integer","method": "htsql","options": {

"expression": "year($birthdate)"}

}]

}

46 Chapter 3. Examples


3.1.4 Web Form


},

"defaultLocalization": "en","title": {"en": "A Web Form for the Simple Example"

},

"pages": [{

"id": "page1","elements": [

{"type": "text","options": {

"text": {"en": "Please answer this short questionnaire."

}}

},

{"type": "question","options": {

"fieldId": "name","text": {"en": "What is your full name?"

}}

},


"fieldId": "birthdate","text": {"en": "What date were you born?"

},"help": {"en": "Please enter the date in YYYY-MM-DD format."

}}

}]

}]

}

3.1. Example of a Simple Definition Set 47


3.1.5 SMS Interaction


},

"defaultLocalization": "en",

"steps": [{

"type": "text","options": {

"text": {"en": "Please answer this short questionnaire."

}}

},


"fieldId": "name","text": {"en": "What is your full name?"

}}

},


"fieldId": "birthdate","text": {"en": "What date were you born?"

}}

}]

}

3.1.6 Assessment


},

"values": {"name": {

"value": "John Smith"},

(continues on next page)



(continued from previous page)

"birthdate": {"value": "1983-10-29"

}},

"meta": {"calculations": {

"uppercase_name": "JOHN SMITH","birth_year": 1983

}}

}

3.2 Example of All Data Types Being Used

Table of Contents

• Example of All Data Types Being Used

– Overview

– Instrument

– Web Form

– Assessment

3.2.1 Overview

The following examples illustrate an Instrument that contains fields of every data type supported by the RIOS specifi-cation. It is accompanied by a Web Form that is broken up into several pages and uses all available element types.

3.2.2 Instrument

{"id": "urn:examples:all-types","version": "1.0",

"title": "A Simple Example",

"record": [{

"id": "float_field","type": "float"

},

{"id": "integer_field","type": "integer"

},


3.2. Example of All Data Types Being Used 49



{"id": "text_field","type": "text"

},

{"id": "enumeration_field","type": {

"base": "enumeration","enumerations": {"red": {},"blue": {},"green": {}

}}

},

{"id": "enumerationset_field","type": {

"base": "enumerationSet","enumerations": {"pizza": {},"taco": {},"sushi": {},"burger": {},"salad": {}

}}

},

{"id": "date_field","type": "date"

},

{"id": "time_field","type": "time"

},

{"id": "datetime_field","type": "dateTime"

},

{"id": "recordlist_field","type": {

"base": "recordList","record": [{"id": "sub_field_1","type": "text"

},





{"id": "sub_field_2","type": "integer"

}]

}},

{"id": "matrix_field","type": {

"base": "matrix","rows": [{

"id": "row_1"},

{"id": "row_2"

}],"columns": [{

"id": "column_1","type": "text"

},

{"id": "column_2","type": "integer"

}]

}}

]}

3.2.3 Web Form

{"instrument": {"id": "urn:examples:all-types","version": "1.0"

},

"defaultLocalization": "en","title": {"en": "All RIOS Data Types"

},

"pages": [{

"id": "basics","elements": [

{(continues on next page)




"type": "header","options": {

"text": {"en": "Basic Field Types"

}}

},


"text": {"en": "This page contains questions associated with basic field types."

}}

},


"fieldId": "text_field","text": {"en": "Please enter some text:"

}}

},


"fieldId": "integer_field","text": {"en": "Please enter an integer:"

}}

},


"fieldId": "float_field","text": {"en": "Please enter a number that includes a decimal:"

}}

}]

},

{"id": "choices","elements": [

{"type": "header","options": {

"text": {"en": "Choice-Based Field Types"





}}

},


"text": {"en": "This page contains questions associated with enumerated-choice

→˓field types."}

}},


"fieldId": "enumeration_field","text": {"en": "What is your favorite color?"

},"enumerations": [{"id": "green","text": {"en": "Green"

}},

{"id": "blue","text": {"en": "Blue"

}},

{"id": "red","text": {"en": "Red"

}}

]}

},

{"type": "divider"

},


"fieldId": "enumerationset_field","text": {"en": "Which of these foods do you enjoy eating?"

},(continues on next page)




"enumerations": [{"id": "taco","text": {"en": "Tacos"

}},

{"id": "salad","text": {"en": "Salads"

}},

{"id": "burger","text": {"en": "Burgers"

}},

{"id": "sushi","text": {"en": "Sushi"

}},

{"id": "pizza","text": {"en": "Pizza"

}}

]}

}]

},

{"id": "temporal","elements": [{

"type": "header","options": {

"text": {"en": "Date/Time-Based Field Types"

}}

},


"text": {(continues on next page)




"en": "This page contains questions associated with date- and time-→˓related field types."

}}

},


"fieldId": "date_field","text": {"en": "Please enter a date:"

}}

},


"fieldId": "time_field","text": {"en": "Please enter a time:"

}}

},


"fieldId": "datetime_field","text": {"en": "Please enter a date and time:"

}}

}]

},

{"id": "complex","elements": [

{"type": "header","options": {

"text": {"en": "Complex Field Types"

}}

},


"text": {"en": "This page contains questions associated with complex field types.

→˓ Play the following audio clip for more information."}





}},

{"type": "audio","options": {

"source": {"en": ["http://example.com/instructions.mp3"

]}

}},


"fieldId": "recordlist_field","text": {"en": "Please enter as many combinations of the following two fields as

→˓you'd like:"},"questions": [{"fieldId": "sub_field_1","text": {"en": "Enter some text:"

}},

{"fieldId": "sub_field_2","text": {"en": "Enter an integer:"

}}

]}

},

{"type": "divider"

},


"fieldId": "matrix_field","text": {"en": "Please fill out the following grid:"

},"rows": [{"id": "row_1","text": {"en": "First Row"

}(continues on next page)




},

{"id": "row_2","text": {"en": "Second Row"

}}

],"questions": [{"fieldId": "column_1","text": {"en": "Enter some text:"

}},

{"fieldId": "column_2","text": {"en": "Enter an integer:"

}}

]}

}]

}]

}

3.2.4 Assessment

{"instrument": {"id": "urn:examples:all-types","version": "1.0"

},

"values": {"float_field": {

"value": 12.3},

"integer_field": {"value": 42

},

"text_field": {"value": "hello world"

},

"enumeration_field": {"value": "blue"

},(continues on next page)




"enumerationset_field": {"value": ["pizza", "taco"]

},

"date_field": {"value": "2015-07-04"

},

"time_field": {"value": "12:34:56"

},

"datetime_field": {"value": "2010-04-01T03:55:24"

},

"recordlist_field": {"value": [

{"sub_field_1": {"value": "foo"

},

"sub_field_2": {"value": 12

}},

{"sub_field_1": {

"value": "bar"},

"sub_field_2": {"value": 9001

}}

]},

"matrix_field": {"value": {

"row_1": {"column_1": {

"value": "happy"},

"column_2": {"value": 1337

}},

"row_2": {"column_1": {

"value": "sad"},





"column_2": {"value": 12345

}}

}}

}}




CHAPTER 4

License

4.1 Apache License

Version 2.0, January 2004 <http://www.apache.org/licenses/>

4.1.1 Terms and Conditions for use, reproduction, and distribution

1. Definitions

“License” shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through9 of this document.

“Licensor” shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.

“Legal Entity” shall mean the union of the acting entity and all other entities that control, are controlled by, or areunder common control with that entity. For the purposes of this definition, “control” means (i) the power, direct orindirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership offifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.

“You” (or “Your”) shall mean an individual or Legal Entity exercising permissions granted by this License.

“Source” form shall mean the preferred form for making modifications, including but not limited to software sourcecode, documentation source, and configuration files.

“Object” form shall mean any form resulting from mechanical transformation or translation of a Source form, includingbut not limited to compiled object code, generated documentation, and conversions to other media types.

“Work” shall mean the work of authorship, whether in Source or Object form, made available under the License, asindicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendixbelow).

“Derivative Works” shall mean any work, whether in Source or Object form, that is based on (or derived from) theWork and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, anoriginal work of authorship. For the purposes of this License, Derivative Works shall not include works that remainseparable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.

61


“Contribution” shall mean any work of authorship, including the original version of the Work and any modifications oradditions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Workby the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. Forthe purposes of this definition, “submitted” means any form of electronic, verbal, or written communication sent tothe Licensor or its representatives, including but not limited to communication on electronic mailing lists, source codecontrol systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of dis-cussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designatedin writing by the copyright owner as “Not a Contribution”.

“Contributor” shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has beenreceived by Licensor and subsequently incorporated within the Work.

2. Grant of Copyright License

Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publiclydisplay, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.

3. Grant of Patent License

Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide,non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made,use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claimslicensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of theirContribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation againstany entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporatedwithin the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You underthis License for that Work shall terminate as of the date such litigation is filed.

4. Redistribution

You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or withoutmodifications, and in Source or Object form, provided that You meet the following conditions:

• (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and

• (b) You must cause any modified files to carry prominent notices stating that You changed the files; and

• (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent,trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertainto any part of the Derivative Works; and

• (d) If the Work includes a “NOTICE” text file as part of its distribution, then any Derivative Works that Youdistribute must include a readable copy of the attribution notices contained within such NOTICE file, excludingthose notices that do not pertain to any part of the Derivative Works, in at least one of the following places:within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation,if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if andwherever such third-party notices normally appear. The contents of the NOTICE file are for informationalpurposes only and do not modify the License. You may add Your own attribution notices within DerivativeWorks that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that suchadditional attribution notices cannot be construed as modifying the License.

You may add Your own copyright statement to Your modifications and may provide additional or different licenseterms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as

62 Chapter 4. License


a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions statedin this License.

5. Submission of Contributions

Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You tothe Licensor shall be under the terms and conditions of this License, without any additional terms or conditions.Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement youmay have executed with Licensor regarding such Contributions.

6. Trademarks

This License does not grant permission to use the trade names, trademarks, service marks, or product names of theLicensor, except as required for reasonable and customary use in describing the origin of the Work and reproducingthe content of the NOTICE file.

7. Disclaimer of Warranty

Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor providesits Contributions) on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, eitherexpress or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT,MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determin-ing the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise ofpermissions under this License.

8. Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required byapplicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable toYou for damages, including any direct, indirect, special, incidental, or consequential damages of any character arisingas a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss ofgoodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), evenif such Contributor has been advised of the possibility of such damages.

9. Accepting Warranty or Additional Liability

While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptanceof support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, inaccepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of anyother Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liabilityincurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additionalliability.

END OF TERMS AND CONDITIONS

4.1.2 APPENDIX: How to apply the Apache License to your work

To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets[] replaced with your own identifying information. (Don’t include the brackets!) The text should be enclosed inthe appropriate comment syntax for the file format. We also recommend that a file or class name and description of

4.1. Apache License 63


purpose be included on the same “printed page” as the copyright notice for easier identification within third-partyarchives.

Copyright [yyyy] [name of copyright owner]

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except incompliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is dis-tributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, eitherexpress or implied. See the License for the specific language governing permissions and limitations underthe License.

64 Chapter 4. License

http://www.apache.org/licenses/LICENSE-2.0

CHAPTER 5

Change History

5.1 RIOS Change History

5.1.1 0.3.0 (2020-01-30)

• Changed license to Apache v2.0.

• Clarified behavior of the length.min constraint with respect to required.

• Clarified behavior of the required property with respect to recordList fields.

• Clarified behavior of the required property with respect to matrix fields, their Rows, and their Columns.

• Clarified the values that should be provided for the min and max of the range constraint.

• Clarified behavior of the enumerations property in Question Objects.

• Clarified Web Form Event types that are applicable to audio elements.

5.1.2 0.2.0 (2015-12-28)

• Changed name of standard to RIOS - Research Instrument Open Standard

• Removed ability to define Calculations with result types of enumeration or enumerationSet, as thosetypes don’t make sense without first defining the set of possible enumerations.

• Clarified that Form Element Tags cannot be the same as Page IDs or Instrument Field IDs.

• Clarified <<Parameter>> markup behavior with respect to null values.

• Clarified type inheritance with respect to overriding constraints.

• Added support for an identifiable flag on Calculations. This flag’s meaning is the same as it is on Instru-ment fields.

• Added support for arbitrary metadata in Instruments, Calculation Sets, Forms, and Interactions via the metaproperty.

65


5.1.3 0.1.0 (2015-08-24)

• Initial publication of PRIMSH for review.

66 Chapter 5. Change History