Instrument Definition Specification

Overview

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

Format

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

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 described within the definition. This id, in conjunction with the version property, is used by Assessment Documents (and/or other supplementary documents) to identify which Instrument Definition they correspond to. Typically, urn-schemed URIs are used, but http -schemed URIs are also valid.
Example:urn:my-organization:an-instrument-name
version
Type:String
Constraints:Required; Must be formatted in a traditional <major>.<minor> software versioning scheme
Description:This property contains a string that uniquely identifies a published revision of this Instrument Definition. This version, in conjunction with the id property, is used by Assessment Documents (and/or other supplementary documents) to identify which Instrument Definition they correspond to. The major portion of the version string should represent a generation of the 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 description of the Instrument described within.
Example:My Example Title
description
Type:String
Description:This property allows the Instrument author to explain what the Instrument is, what it’s being used for, or any other helpful information about the Instrument. This property is optional and 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 the definition. This property is optional.
types
Type:Type Collection Object
Description:This property allows the Instrument author to define common data types/restrictions that 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 responses for.

Field Object

Field Objects are the core of what makes up an Instrument Definition. They describe the data points the Instrument wants 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 subsequent documents. 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 being used for, or any other helpful information about the Field. This property is optional and is not intended to ever be shown to an end-user.
type
Type:Enumerated String or Type Object
Constraints:Required
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 of one of the Types defined in the Type Collection Object, or it can be a Type Object that defines a Type 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 least one non-empty response set in the list. For matrix fields, this means that at least one cell in the matrix contains a value.
annotation
Type:

Enumerated String
Description:

Indicates whether or not this Field allows for an additional text-based response that allows the respondent to explain why they can’t or won’t provide a response for this Field. This property is optional, and, if not specified, is assumed to be none. If this Field is marked as required, this property cannot be any value other than none.
PossibleValues:
  • required - If no value for the field has been collected, an annotation must be collected for this Field.
  • optional - An annotation may be collected for this Field.
  • none - An annotation is not allowed for this Field.
explanation
Type:

Enumerated String
Description:

Indicates whether or not this Field allows for an additional text-based response that allows the respondent to provide more detail or to further explain the main response to this Field. 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 information that can be used to identify the subject or respondent. This is typically used to flag fields that would contain information that could be classified as “Protected Health Information” (HIPAA PHI), “Personally Identifiable Information” (NIST PII), “Personal Data” (EU Data Protection Directive), etc. This property is optional, and, if not specified, is assumed to be false. If a recordList 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 data types/restrictions that can then be referred to throughout the rest of the Instrument Definition. This object consists of one or more properties where the property name serves as a unique identifier for the Type (in the format of an Identifier), 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 a Field. Not only does it specify the base data type (e.g., text vs integer vs date), but it also allows the author to place additional restrictions or constraints on the data.

base
Type:

Enumerated String
Constraints:

Required
Description:

This property indicates the base Type that this Type Object will inherit its basic properties from. All Types defined in an Instrument Definition must inherit from either one of the Base Types, 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 any constraints also defined in this Type Object will completely override constraints by the same name 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 base Type 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 are specified, 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 minimum and/or maximum character length that the response can be. For enumerationSet response types, this property allows the definition author to specify the minimum and/or maximum number of enumerations the respondent can select. For recordList response types, this property allows the definition author to specify the minimum and/or maximum number of response sets the respondent can provide for this Field. If this Field is also marked as required, then the minimum value cannot be lower than one. Note that setting a min is not equivalent to marking the field 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 order to be considered a valid response.
Example:^[A-Z0-9]$
enumerations
Type:Enumeration Collection Object
Constraints:Required for enumeration and enumerationSet Types
SupportedBaseTypes:
 enumeration, enumerationSet
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 listed in 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 for reach row.

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 subsequent documents. 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’s being used for, or any other helpful information about the Column. This property is optional.
type
Type:Enumerated String or Type Object
Constraints:Required
Description:This property identifies the type of data that will be returned as a response to this Column. It can be specified by either indicating the identifier of one of the simple Base Types, the identifier of one of the Types defined in the Type Collection Object, or it can be a Type Object that defines a simple Type directly within this Field. Ultimately, the type must be based on a simple type.
required
Type:Boolean
Description:Indicates whether or not a response is required for this Column. This means that for any Row in the matrix where at least one Column is populated with a value, this Column must also 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 information that can be used to identify the subject or respondent. This is typically used to flag fields that would contain information that could be classified as “Protected Health Information” (HIPAA PHI), “Personally Identifiable Information” (NIST PII), “Personal Data” (EU Data Protection Directive), 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
Constraints:Required; Must be an Identifier
Description:This property uniquely identifies the data point so that it can be referred to in subsequent documents. 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 being used 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 least one column in this Row contains a value. This property is optional, and, if not specified, is assumed to be false.

Base Types

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

Identifier Class Description
float simple A floating-point numeric value.
integer simple An integer value.
text simple A string value.
enumeration simple A string value that must be chosen from a predefined set of values.
enumerationSet simple An array of one or more string values that must be chosen from a predefined set of values.
boolean simple Either a true or false value.
date simple A string value representing a date in time. Must be formatted as an ISO 8601 extended format calendar date (YYYY-MM-DD).
time simple A string value representing a time of day. Must be formatted as an ISO 8601 extended format time (HH:MM:SS).
dateTime simple A string value representing the time on a specific date. Must be formatted as an ISO 8601 extended format date and time combination (YYYY-MM-DDTHH:MM:SS).
recordList complex An array of multiple-response collections, where each element in the array is the same set of simple Fields being responded to multiple times.
matrix complex 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 lower bounds 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 property is optional, and, if not specified, is assumed to represent the fact that there is no lower bound other 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 property is optional, and, if not specified, is assumed to represent the fact that there is no lower bound other 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 unique identifier for the enumeration, and the value of the property is the definition of the enumeration, in the format of a Enumeration 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 documents) 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 Field that 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, what it’s being used for, or any other helpful information about the Enumeration. This property is optional.

Identifier

Identifiers are strings that adhere to the following restrictions:

  • Consists of 2 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)
  • The first character is an alphabetic character.
  • The last character is not an underscore.
  • Does not contain consecutive underscore characters.

Example Identifiers:

  • 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 Metadata Collection Object has no required or predefined properties, and can therefore contain any (legal JSON) property names and value data types. Software that consumes Instrument Definitions must ignore any property whose name it does not recognize or support.

Property Name Data Type Example Description
author String John Smith A string that describes the entity that created this definition.
copyright String 2009, Smith Instrumentation A string that describes who owns the copyright to the Instrument implemented by this definition.
homepage String http://www.example.com A URL (as described by RFC1738) to a web page that has more information about this Instrument.
generator String SurveyBuilder/1.0 A string that indicates what application produced the Instrument Definition. This must should be formatted similarly to HTTP Product Token strings as specified in RFC2616.