QuML Question Spec

This document contains the QuML question spec that needs to be implemented by player and editor. This document has two sections

1. Key Attributes of question and their behaviour

2. Question session workflow that needs to be implemented by the QuML question player

Attributes

body

Body contains the text, graphics, media objects and interactions that describe the question’s content and information about how it is structured. Body can be either a String or a Map, based on whether the question is created for usage in one language or multiple languages.

Body can contain following types of HTML elements:

• Structural HTML elements like <div>, <span>, <figure>, <ul> and <li>

• Media elements like <img>, <audio> and <video>

• Input elements like text input, text area, select, options, check box, radio buttons, file upload and canvas elements

In addition to the standard HTML elements and attributes, body can also contain the following:

• Usage of “data-*” attributes to specify the interactions on HTML elements, bind response variables to the interactions, use media and template variables.

  • In addition to “data-*” attributes, body will also have HTML comments as placeholders for the interactions

• Usage of standard style classes defined by the specification. QuML players should provide implementation for the defined classes.

“data-*“ attributes and HTML comments - are used for the following purposes:

Interactions

A question can contain zero or more interactions with the user. Most of these interactions are typical question types (for example, multiple choice, order elements, fill in the blanks). Interactions can also be used for activities like "upload document," "draw a picture," and "start a film". Interactions can be defined in the body using HTML data attributes like “data-<interaction_name>-interaction”. Following interactions should be supported in the current version:

• data-choice-interaction: For multiple choice questions which can have more than one option as the correct answer

• data-text-interaction: For fill in the blank questions where user has to input a text as the response

• data-select-interaction: For questions where user has to select one or more options from a list

• data-match-interaction: For match the following question types where user matches the options

QuML player should provide the implementation for all the defined interaction types. QuML player should capture the response provided by the user for the interactions within the question and bind them with the specified response variables.

Response Variables

Response variables are used to capture the response of a user. Each response variable declared may be bound to one & only one interaction and defined using the html data attribute: “data-response-variable”.

In the above sample, there is response variable named “response_01” defined on the HTML input element. When user enters a value in this text box, QuML player should set the entered value as the value for the variable “response_01”.

In the above sample, the response variable “responseValue“ should be set to “1” when user selects this option in a MCQ question. The expected value and the scoring logic for each response variable is declared in the “responseDeclaration” section of the question.

Asset Variables

Asset variables are used to load assets during the rendering of a question. Values for asset variables refer to an asset in the QuML repository server. Asset variables can be used in a question using the html data attribute: “data-asset-variable”. This data attribute should be set on HTML elements that are used for rendering assets (e.g. img, audio and video elements). And when the question is being rendered, the location of the asset object represented by the asset variable is set as the source of the HTML element on which the asset variable is declared.

All the assets used in a question are declared in “media“ section of the question. This declaration is needed to package and pre-download the question assets for offline usage.

Style classes - QuML specification has defined set of standard classes for various sections, elements and interactions in a question

• question body styles

  • question-body: for overall question body

  • 2-col-layout: for questions rendered in two columns. e.g: 2-col MCQ questions where question body is in one column and options are presented in the second column

  • question-column: for defining columns in questions with 2-col-layout

• image styles

  • img-small: use 25% of the available width and scales the image accordingly. 50% or 100% width may also be used for these images when available width is below certain specified values.

  • img-medium: use 50% of the available width and scales the image accordingly. 100% width may also be used for these images when available width is below certain specified values.

  • img-large: always use 100% of the available width

  • img-align-left

  • img-align-right

• MCQ options styles

  • mcq-options-vertical: always show options vertically

  • mcq-options-grid: show options in a grid. if available width is small, fall back to vertical layout.

  • mcq-options-horizontal: show options horizontally. if the available width is small, fall back to grid or vertical layout.

• Input text styles: these classes should be used for text interaction elements.

  • text-small:

  • text-medium:

  • text-large:

• Drop down styles: these classes should be used for single & multi select interaction elements.

  • drop-down:

solutions

Providing exemplar answers for questions aid candidates in-depth learning and enhance user’s understanding of the concepts. Multiple solutions can be configured for a question.

Similar to body, solutions in multiple languages can be specified:

Solutions HTML must contain only structural and media HTML elements. There should be interactions in a solution and hence no input HTML elements. QuML players should allow the users to view the solutions if the context in which the question is being used allows the users to view the solution.

instructions

Instructions on how to understand, attempt or how the question will be evaluated.

Similar to body, instructions in multiple languages can be specified:

Instructions HTML also must contain only structural and media HTML elements. There should be interactions in a solution and hence no input HTML elements.

hints

Similar to body, hints in multiple languages can be specified:

media

“media” attribute contains information about the assets used in the question. It should have declaration for every asset used in the question across body, feedback, instructions, hints and solutions.

QuML players should use absolute path (baaseUrl + src) of the asset during online usage of the question and in case of offline usage, the asset should be pre-downloaded to the device/system where the question is being used.

interactionTypes

List of interactions present in the question body. This list can be null if there are no interactions in the question.

interactions

responseDeclaration

A “responseDeclaration” contains information about the response to a question: When is it correct, and (optionally) how is it scored?

Response Declaration should have declaration for every response variable in the question body. Optionally, the declaration can have the following details:

• Correct Response: Correct (or optimal) values for the response variable

• Mapping to Score: Map different values to score so that a response can have more nuances than plain right or wrong, e.g.: a multiple choice question with more than one correct answer can support partial scoring

• Hints: hints to be shown for this response variable. Hints are shown only if they are allowed in the context where the question is being used.

Examples:

scoringMode

Scoring mode of the question:

• system: evaluated and score is generated by the platform (e.g. within the player using the response declaration info).

• none: question has no evaluation and score is never generated for such questions.

maxScore

Maximum score for the question. Default value will be 1. Creator can update to a higher value. Score for each response mapping should not be greater than this.

timeLimit

Hard time limit for the question - in seconds. User has to provide response within this time limit.

timer

Show or hide timer when playing this question.

editorState

Used by editors to store question data in a format compatible to the editor.

qumlVersion

Version of the QuML used to create the question.

showFeedback

Display feedback if this flag is set to true

showSolutions

Allow users to view solution if this flag is set to true

Question Session

A QuML question comprises of multiple components with a well-defined structure. Each component of the question comes into play at different states of a question session. QuML implementations (players) should use these components and perform the required action in-between state transitions. Below are the different states in a question play session:

• start - start of the question play

• interacting - when user is interacting with the question and providing his/her responses. and optionally, may be viewing hints also.

• feedback - feedback is rendered to the users based on their responses

• solution - user is viewing the solutions for the question, if solutions are available for the question and the question playing context allows users to view the solution

• review - user is reviewing the responses provided, if the question playing context allows users to review their responses

• finished - response processing is complete and outcomes (SCORE, duration, FEEDBACK to be shown) are computed by the player

State Transitions

QuML players should do certain actions while transitioning from one state to another:

start → interacting: QuML player should load assets, render instructions & body (in the user’s language if multiple languages are supported by the question) and apply the stylesheet.

interacting → interacting: should capture user responses, set values for response variables and show hints (if applicable).

interacting → solution: should render the solutions of the question. question will move into this state by explicit action from user to view the solution.

interacting → finished: should process responses using responseDeclaration and set outcomes (like SCORE, FEEDBACK). And also generate the required telemetry events.

finished → feedback: should render the feedback. question will move into this state automatically if “showFeedback” is set true.

finished → review: should render the question body with user responses.

Outcome Variables

Every question session should compute and set values for certain outcome variables at the end of a question sessions. These outcome variables are used for multiple purposes:

• display feedback

• generate telemetry events

• used by QuestionSet player to compute the overall question set score (or other outcome variables), if this question is being rendered as part of a question set.

Following are the outcome variables that should be set by the QuML players:

• SCORE: score attained by the user. It should be a float value.

• numAttempts: an integer that records the number of attempts of each question the user has taken (if multiple attempts are allowed in the context where the question is being used). The value defaults to 0 initially and then increases by 1 at the start of each attempt.

• duration: a float that records the accumulated time (in seconds) in an attempt. In other words, the time between the beginning and the end of the question session minus any time the session was in the suspended state (TBD: what should be set as duration in case of multiple attempts).

• completionStatus: completion status of the question. one of complete, incomplete, skipped or unknown.