Latest Specification (0.3.0)

Status

This page presents the latest published version of USEF, which currently is 0.3.0. The specification uses semantic versioning to clearly signal any breaking changes. The specification is still in an early alpha stage and is likely to change before the initial 1.0 release.

If you catch an error in the specification’s text, or if you want to contribute to evolving the specification, or if you write an implementation, please let us know by opening an issue or pull request at our GitHub repository.

Introduction

The User Study Exchange Format (USEF) is a specification for the exchange of parts of or complete User Studies. In particular it focuses on those aspects that gather self-reported responses from study participants.

It defines both the core data-types to be used and generic instances for some of these data-types.

Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Core and Optional

The USEF is split into core and optional parts. Conforming implementations MUST implement all core parts of the specification and MAY implement all optional parts. Conforming implementations MUST be able to interoperate with other implementations that do or do not implement the optional parts.

Data-Format

The USEF uses JSON:API as its data-format. In particular it uses the compound JSON:API document structure to store all required data in a single file, without requiring access to additional, external resources. An USEF document MUST also conform to the rules specified in the JSON:API specification.

Data-Types

The USEF consists of one core and four optional data-types. The Question is the only core data-type and represents both generic questions (single input, multiple choice, …) and specific questions (gender, age, education, …) and MUST be implemented by all conforming implementations. The three optional data-types are the Page, representing a collection of Questions, the Study, representing a collection Pages, and the Transition, representing the transitions between Pages.

Question

The Question is the primary building block of the USEF and the only data-type that is core and MUST be implemented by all conforming implementations. The Question is used to represent both generic questions (single input, multiple choice, …), where the researcher using the Question must provide further details before it can be shown to study participants, and also specific questions (gender, age, education, …) that can be re-used as they are.

The Question object MUST have the following members:

• id: The identifier of the Question, which must be unique with regards to all Questions in the document.
• type: "questions".
• links: A single links object.
• attributes: A single question attributes object.
• relationships: A single question relationships object (the only exception is the core USEFQuestion, which does not have any relationships).

The Question implements an inheritance hierarchy, which includes a set of 9 standard questions that MUST be implemented. The inheritance is important for the question attributes object, as attributes are inherited from all ancestor Questions.

An example question would look like this:

{
  "id": "AgeQuestion"
  "type": "questions",
  "links": {
    "self": "https://example.org/my-study/questions/gender"
  },
  "attributes": {
    "title": "Please select your age band:"
    "answers": [
      "1",
      "2",
      "3",
      "4",
      "5",
      "6",
      "7",
      "8"
    ],
    "labels": [
      "< 18",
      "18 - 25",
      "26 - 35",
      "36 - 45",
      "46 - 55",
      "56 - 65",
      "66 - 75",
      "> 75"
    ],
    "version": "1.0.0"
  },
  "relationships": {
    "parent": {
      "data": {
        "type": "questions",
        "id": "USEFSingleChoice"
      }
    }
  }
}

Question Attributes

The question attributes object MUST contain the following key:

• version: A semantic version number.

Additionally it MAY contain all the attributes that define the question to be shown to the participant. The values for each question attributes MUST be drawn from one of the following three categories:

• null: This key MUST be ignored by conforming implementations.
• an object: This key MUST be interpreted as listed below
• other value: To be treated as a constant value that MUST be used as provided.

Question Attribute Object

The Question Attribute Object defines how the attribute value is to be acquired. It MUST contain the following keys:

• source: The source to acquire the attribute value from. It MUST be set to "user".

• type: The type of value to be acquired. A conforming application MUST support the following values:

  • "singleValue": A single value to be acquired from the user.
  • "multiLineTextValue": A single value to be acquired from the user using a multi-line textbox.
  • "booleanValue": A boolean value to be acquired from the user.
  • "listOfValues": A list of values to be acquired from the user.
  • "label": The label to show to the user when editing this attribute.

  Other values MAY be used to extend the functionality, but these MUST be prefixed.

Additionally it MAY contain any of the following keys:

• allowed: A list of values that are allowed for this attribute.

Question Relationships

The question relationships object MUST contain the following key:

• parent: A resource linkage object as specified in JSON:API. This MUST include the data key to identify the linked object in the included resource objects. The type of the linked object MUST be another Question. If a parent Question is provided, then any properties and relationships specified in the parent Question are inherited, but MAY be overriden by specifying that attribute. The exception is the version key, which MUST be provided for each Question.

Standard Questions

The USEF provides the following eight base questions which MUST be supported:

• USEFQuestion
• USEFDisplay
• USEFSingleLineInput
• USEFMuliLineInput
• USEFSingleChoice
• USEFMultiChoice
• USEFHidden
• USEFSingleChoiceGrid
• USEFMultiChoiceGrid

USEFQuestion

The USEFQuestion is the root Question type, from which all other Questions MUST inherit. It has three attributes:

• title: The title displayed to study participants.
• required: Whether a response to the question is required or not. The value MUST be one of true or false.

{
  "id": "USEFQuestion",
  "type": "questions",
  "links": {
    "self": "https://biirrr.github.io/usef/questions/USEFQuestion/v0_2_0.json"
  },
  "attributes": {
    "version": "0.2.0",
    "title": {
      "source": "user",
      "type": "singleValue"
    },
    "required":{
      "source": "user",
      "type": "booleanValue"
    }
  }
}

USEFDisplay

The USEFDisplay is a question that is used to display information to the study participants without requiring them to provide any response. It has four attributes:

• title: Overrides the parent USEFQuestion, setting it to null as all information to display to the participant MUST be in the content attribute.
• required: Overrides the parent USEFQuestion, setting it to null as this question does not generate any response.
• content: The content to show to the participant.
• format: The format to use for interpreting the content. All conforming applications MUST support the formats text/text (interpret the content as pure text) and text/html (interpret the content as HTML5).

{
  "id": "USEFDisplay",
  "type": "questions",
  "links": {
    "self": "https://biirrr.github.io/usef/questions/USEFDisplay/0.2.0.json"
  },
  "attributes": {
    "version": "0.2.0",
    "title": null,
    "required": null,
    "content": {
      "source": "user",
      "type": "muliLineTextValue"
    },
    "format": {
      "source": "user",
      "type": "singleValue"
    }
  },
  "relationships": {
    "parent": {
      "data": {
        "type": "questions",
        "id": "USEFQuestion"
      }
    }
  }
}

USEFSingleLineInput

The USEFSingleLineInput is a question that allows the study participant to provide a single textual response. It has a single attribute:

• validation: Validation to apply to the participant’s response as a regular expression.

{
  "id": "USEFSingleLineInput",
  "type": "questions",
  "links": {
    "self": "https://biirrr.github.io/usef/questions/USEFSingleLineInput/v0_2_0.json"
  },
  "attributes": {
    "version": "0.2.0",
    "validation": {
      "source": "user",
      "type": "singleValue"
    }
  },
  "relationships": {
    "parent": {
      "data": {
        "type": "questions",
        "id": "USEFQuestion"
      }
    }
  }
}

USEFMultiLineInput

The USEFMultiLineInput is a question that allows the study participant to provide a multi-line textual response. It has no additional attributes.

{
  "id": "USEFMultiLineInput",
  "type": "questions",
  "links": {
    "self": "https://biirrr.github.io/usef/questions/USEFMultiLineInput/v0_2_0.json"
  },
  "attributes": {
    "version": "0.2.0"
  },
  "relationships": {
    "parent": {
      "data": {
        "type": "questions",
        "id": "USEFQuestion"
      }
    }
  }
}

USEFSingleChoice

The USEFSingleChoice is a question that allows the study participant to select a response from a selection of pre-defined responses. It has three attributes:

• values: The list of values that the participant can select from.
• labels: The list of labels to show for the values. If no labels are provided, then the values are directly showed to the participants.
• display: How to display the values / labels, MUST be one of dropdown (display as a drop-down selection where only the selected value is visible), vertical list (display as a vertical list to select from, where all values are visible), or horizontal list (display as a horizontal list to select from, where all values are visible).

{
  "id": "USEFSingleChoice",
  "type": "questions",
  "links": {
    "self": "https://biirrr.github.io/usef/questions/USEFSingleChoice/v0_2_0.json"
  },
  "attributes": {
    "version": "0.2.0",
    "values": {
      "source": "user",
      "type": "listOfValues"
    },
    "labels": {
      "source": "user",
      "type": "listOfValues"
    },
    "display": {
      "source": "user",
      "type": "singleValue",
      "allowed": ["dropdown", "vertical list", "horizontal list"]
    }
  },
  "relationships": {
    "parent": {
      "data": {
        "type": "questions",
        "id": "USEFQuestion"
      }
    }
  }
}

USEFMultiChoice

The USEFMultiChoice is a question that allows the study participant to select one or more responses from a selection of pre-defined responses. It has three attributes:

• values: The list of values that the participant can select from.
• labels: The list of labels to show for the values. If no labels are provided, then the values are shown to the participants.
• display: How to display the values / labels, MUST be one of multiselect (display as a list selection where only a sub-set of the values is visible), vertical list (display as a vertical list to select from, where all values are visible), or horizontal list (display as a horizontal list to select from, where all values are visible).

{
  "id": "USEFMultiChoice",
  "type": "questions",
  "links": {
    "self": "https://biirrr.github.io/usef/questions/USEFMultiChoice/v0_2_0.json"
  },
  "attributes": {
    "version": "0.2.0",
    "values": {
      "source": "user",
      "type": "listOfValues"
    },
    "labels": {
      "source": "user",
      "type": "listOfValues"
    },
    "display": {
      "source": "user",
      "type": "singleValue",
      "allowed": ["multiselect", "vertical list", "horizontal list"]
    }
  },
  "relationships": {
    "parent": {
      "data": {
        "type": "questions",
        "id": "USEFQuestion"
      }
    }
  }
}

USEFHidden

The USEFHidden is a question that represents a hidden response. It has the following attribute:

• value: The value to use as the hidden response

{
  "id": "USEFHidden",
  "type": "questions",
  "links": {
    "self": "https://biirrr.github.io/usef/questions/USEFHidden/v0_2_0.json"
  },
  "attributes": {
    "version": "0.2.0",
    "title": null,
    "value": {
      "source": "user",
      "type": "singleValue"
    }
  },
  "relationships": {
    "parent": {
      "data": {
        "type": "questions",
        "id": "USEFQuestion"
      }
    }
  }
}

USEFSingleChoiceGrid

The USEFSingleChoiceGrid is a question that shows the participants a number of rows and for each row the participant can select one response from a selection of pre-defined responses. All rows share the same set of pre-defined responses. It has the following four attributes:

• column_values: The list of values that the participant can select from.
• column_labels: The list of labels to show for the values. If no column_labels are provided, then the column_values are shown to the participants.
• row_values: The list of unique values identifying each row.
• row_labels: The list of labels to show for each row. If no row_labels are provided, then the row_values are shown to the participants.

{
  "id": "USEFSingleChoiceGrid",
  "type": "questions",
  "links": {
    "self": "https://biirrr.github.io/usef/questions/USEFSingleChoiceGrid/v0_2_0.json"
  },
  "attributes": {
    "version": "0.2.0",
    "column_values": {
      "source": "user",
      "type": "listOfValues"
    },
    "column_labels": {
      "source": "user",
      "type": "listOfValues"
    },
    "row_values": {
      "source": "user",
      "type": "listOfValues"
    },
    "row_labels": {
      "source": "user",
      "type": "listOfValues"
    }
  },
  "relationships": {
    "parent": {
      "data": {
        "type": "questions",
        "id": "USEFQuestion"
      }
    }
  }
}

USEFMultiChoiceGrid

The USEFMultiChoiceGrid is a question that shows the participants a number of rows and for each row the participant can select one or more responses from a selection of pre-defined responses. All rows share the same set of pre-defined responses. It has the following four attributes:

• column_values: The list of values that the participant can select from.
• column_labels: The list of labels to show for the values. If no column_labels are provided, then the column_values are shown to the participants.
• row_values: The list of unique values identifying each row.
• row_labels: The list of labels to show for each row. If no row_labels are provided, then the row_values are shown to the participants.

{
  "id": "USEFMultiChoiceGrid",
  "type": "questions",
  "links": {
    "self": "https://biirrr.github.io/usef/USEFMultiChoiceGrid/v0_2_0.json"
  },
  "attributes": {
    "version": "0.2.0",
    "column_values": {
      "source": "user",
      "type": "listOfValues"
    },
    "column_labels": {
      "source": "user",
      "type": "listOfValues"
    },
    "row_values": {
      "source": "user",
      "type": "listOfValues"
    },
    "row_labels": {
      "source": "user",
      "type": "listOfValues"
    }
  },
  "relationships": {
    "parent": {
      "data": {
        "type": "questions",
        "id": "USEFQuestion"
      }
    }
  }
}

Page

A Page is an ordered collection of Questions, which together form a cohesive unit in the study. These might be a set of questions that together acquire descriptive demographics about participants, but they also might be something more focused, such as a single instrument. Questions in the Page MUST be displayed in the order specified in the questions relationship.

The Page object MUST have the following members:

• id: The identifier of the Page, which must be unique with regards to all Pages in the document.
• type: "Page".
• links: A single links object.
• attributes: A single page attributes object.
• relationships: A single page relationships object.

An example Page would look like this:

{
  "id": "Background",
  "type": "Page",
  "links": {
    "self": "https://example.org/my-study/pages/background"
  },
  "attributes": {
    "title": "About you"
  },
  "relationships": {
    "questions": [
      {
        "data": {
          "type": "questions",
          "id": "AgeQuestion"
        }
      },
      {
        "data": {
          "type": "questions",
          "id": "GenderQuestion"
        }
      }
    ]
  }
}

Page Attributes

The page attributes object MUST contain the following key:

• title: The title to show to participants.

Page Relationships

The page relationships object MUST contain the following key:

• questions: An ordered lists of Questions that belong to the Page and MUST be displayed in the order specified here.

The page relationships object MAY contain the following key:

• transitions: An ordered list of Transitions that are to be used to determine the next Page to show to the participant. If multiple Transitions are provided, then all but the last one MUST have conditions specified. To determine which Transition to follow, the Transitions are evaluated in the order specified in this relationship.

Study

The Study groups a set of Pages into a cohesive whole. The ordering of Pages in the Study MUST be used as the ordering when displaying the Pages to participants, except if Transitions are also provided, in which case those MUST be used.

The Study object MUST have the following members:

• id: The identifier of the Study.
• type: "Study".
• links: A single links object.
• attributes: A single study attributes object.
• relationships: A single study relationships object.

An example Study would look like this:

{
  "id": "SampleStudy",
  "type": "Study",
  "links": {
    "self": "https://example.org/my-study"
  },
  "attributes": {
    "title": "My Study",
    "description": "An example study"
  },
  "relationships": {
    "pages": [
      {
        "data": {
          "type": "Page",
          "id": "Welcome"
        }
      },
      {
        "data": {
          "type": "Page",
          "id": "Background"
        }
      }
    ]
  }
}

Study Attributes

The study attributes object MUST contain the following key:

• title: The title to show to participants.

Study Relationships

The page relationships object MUST contain the following key:

• questions: An ordered lists of Pages that belong to the Study and MUST be displayed in the order specified here. The exception is if Transitions are provided, then any Transitions specified on an individual Page override the order specified here. If there are no Transitions for a Page or all Transitions specified for a Page have conditions that do not hold, then the next Page to display MUST be determined by the order of this attribute.

Transition

The Transition represents the link between two Pages, the source Page the participant views first and the target Page the participant transitions to after completing the source Page’s Questions.

A Page can have multiple Transitions, provided that the Transitions have conditions specified on them. In its initial version the USEF only supports a single condition type, namely Transitions conditional on responses provided by participants to previous Questions.

The Transition object MUST have the following members:

• id: The identifier of the Transition.
• type: "Study".
• links: A single links object.
• attributes: A single transition attributes object.
• relationships: A single transition relationships object.

An example Transition would look like this:

{
  "id": "NoConsentTransition",
  "type": "Transition",
  "link": {
    "self": "https://example.org/my-study/pages/Welcome/NoConsentTransition"
  },
  "attributes": {
    "condition": {
      "type": "response",
      "page": "Welcome",
      "questions": ""
    }
  },
  "relationships": {

  }
}

Transition Attributes

The transition attributes object MAY contain the following key:

• condition: A Condition object.

Condition

The condition object MUST contain the following key:

• type: The type of condition. MUST be “response”.

Which other keys MUST be specified depends on the type attribute.

Condition Type "response"

The "response" condition defines a conditional transition based on the participant’s response to a question. It MUST contain the following keys:

• page: The unique identifier of the Page that the response was recorded from.
• question: The unique identifier of the Question that the response was recorded for.
• value: The value to compare the response to.
• comparison: The comparison operator MUST be one of "==" (the condition holds if the response is equal to the value) or "!=" (the condition holds if the response is not equal to the value).

The response MAY also contain the following key IF the Question is a USEFSingleChoiceGrid or USEFMultiChoiceGrid:

• row: The value from the row_values attribute that the response was recorded for.

Transition Relationships

The transition relationships object MUST contain the following key:

• target: The Page to transition to IF no condition is specified or if the condition holds.