Version 1
This is a DRAFT document. We welcome feedback as this format evolves.
Here's a sample qwiklabs.yaml file with all nested details removed to make it
easier to see the general file structure.
entity_type: Exam
schema_version: 1
passing_percentage: 67
default_locale: en
duration: 120
randomize_items: true
randomize_options: true
randomize_prompts: true
retake_cooldown:
- 1
- 7
title:
locales:
en: My Excellent Exam
forms: ...Note that all of the localized content (stem, option titles, etc) are HTML content that may be displayed in various contexts. All of these chunks will be sanitized according to the restricted set in the HTML spec.
| attribute | required | type | notes |
|---|---|---|---|
| default_locale | ✓ | string | Corresponds to the locale that the exam is authored in. Authoring tools can use this as a hint to notify localizers when content in the default locale is updated. Also, it provides a hint to the learner interface about which locale to display if an instruction/resource is not localized for the learner's current locale. |
| schema_version | ✓ | integer | Which version of the exam bundle schema you are using |
| title | dictionary | A locale dictionary of the exam title, such as "My Excellent Exam" | |
| introduction | dictionary | A locale dictionary of the exam introduction to show before a student starts the exam. May include a description, any terms and conditions, instructions, etc. | |
| passing_percentage | ✓ | integer | The threshold grade that a student needs to achieve in order to count as "passing" the exam. |
| duration | ✓ | integer | The maximum time a student is allotted for the exam, in minutes. |
| randomize_items | ✓ | boolean | Whether items in forms should be presented in a random order; true by default |
| randomize_options | ✓ | boolean | Whether options in items should be presented in a random order; true by default |
| randomize_prompts | ✓ | boolean | Whether prompts in match items should be presented in a random order; true by default |
| show_score | boolean | Whether to show student areas for study if failed exam; false by default |
|
| retake_cooldown | ✓ | array | An array of n number of days specifying the cooldown period between retakes; the last number will be the cooldown period for all retakes after the nth |
| forms | ✓ | array | An array of forms (see below for details) |
Forms are versions of an exam. An exam may have multiple forms (i.e. A and B), where A and B will have a different collection of items. One student taking an exam may get form A, and another form B, but both students are considered to be taking "equivalent" exams.
id: form-0
name: FormA
sections: ...| attribute | required | type | notes |
|---|---|---|---|
| id | ✓ | string | A unique identifier for this form, to be consistent across revisions |
| name | ✓ | string | A name for this form |
| sections | ✓ | array | An ordered array of sections (see below for details) in this form |
Sections are groupings of related exam items.
name: Networking
items: ...| attribute | required | type | notes |
|---|---|---|---|
| name | ✓ | string | A name for this section |
| items | ✓ | array | An ordered array of items (see below for details) in this section |
Items are polymorphic - i.e. there are several different item types that are
defined slightly differently. items is an array of dictionaries with
appropriate attributes for the given type. The allowed values for type are:
multiple-choicemultiple-selectmatch
An exam item that has multiple options and one answer. One option is the answer, and the rest are distractors. There must be exactly one answer.
| attribute | required | type | notes |
|---|---|---|---|
| id | ✓ | string | A unique identifier for this item |
| type | ✓ | string | The item type, which is always multiple-choice |
| stem | ✓ | dictionary | A locale dictionary of the text that asks the question, such as "Which of the following is a color?" |
| options | ✓ | array | An array of options (see below for details); order does not matter |
| seed | ✓ | boolean | true if this item is not to be graded; false by default |
| code | string | A unique identifier for this item generated by and for the item author |
An exam item that has multiple options, any number of which are answers. Correct options are answers, and incorrect options are distractors.
| attribute | required | type | notes |
|---|---|---|---|
| id | ✓ | string | A unique identifier for this item |
| type | ✓ | string | The item type, which is always multiple-select |
| stem | ✓ | dictionary | A locale dictionary for the text that asks the question, such as "Which of the following is a color?" |
| options | ✓ | array | An array of options (see below for details); order does not matter |
| seed | ✓ | boolean | true if this item is not to be graded; false by default |
| code | string | A unique identifier for this item generated by and for the item author |
An exam item that has multiple stems with a "lead in" prompt. The correct option for each matching stem is directly specified as the answer. A match item will be scored based on correctly matching all the stems.
| attribute | required | type | notes |
|---|---|---|---|
| id | ✓ | string | A unique identifier for this item |
| type | ✓ | string | The item type, which is always match |
| lead_in | ✓ | dictionary | A locale dictionary of text that provides a lead-in, such as "Can You Match the Capital City to the Correct US State?" |
| stems | ✓ | array | An array of matching stems (see below for details); order does not matter |
| options | ✓ | array | An array of options (see below for details); order does not matter |
| seed | ✓ | boolean | true if this item is not to be graded; false by default |
| code | string | A unique identifier for this item generated by and for the item author |
Match items need an additional stems array which contains the question(s) for which the user must provide the matching answer.
| attribute | required | type | notes |
|---|---|---|---|
| id | ✓ | string | A unique ID for this match Stem |
| title | ✓ | dictionary | A locale dictionary for the content of this stem, such as "Springfield" |
| answer | ✓ | string | ID for option that is the answer for this stem |
multiple-choice and multiple-select, and match items all have an options
array which contains all of the answer(s) and distractors that the user may
choose from. Options are defined for both item types below:
| attribute | required | type | notes |
|---|---|---|---|
| id | ✓ | string | A unique ID for this Option |
| title | ✓ | dictionary | A locale dictionary for the content of this option, such as "Blue" |
| is_answer | ✓ | boolean | true if this option is an answer, and false if it is a distractor (not used for match type) |