Exercise Specification

This page describes the exercise specification format for programmatically creating exercises via the session/create and exercise/validate API endpoints. Use this format when you want to define exercises in code rather than using the Algebrakit CMS or authoring components.

Minimal Example

A minimal exercise with a single multistep interaction that asks the student to simplify an expression:

{
  "type": "AK_Exercise",
  "version": 1,
  "studentProfile": "your-profile-id",
  "questionMode": "ALL_AT_ONCE",
  "symbols": [
    { "name": "x", "type": "VARIABLE" }
  ],
  "elements": [
    {
      "blocks": [
        {
          "type": "CONTENT",
          "content": "Simplify the following expression."
        },
        {
          "type": "INTERACTION",
          "interaction": {
            "type": "MULTISTEP",
            "solutionPart": {
              "task": {
                "type": "SIMPLIFY",
                "expression": "3x + 2x"
              }
            }
          }
        }
      ]
    }
  ]
}

Top-Level Properties

Property Type Required Description
type string Yes Must be "AK_Exercise"
version number Yes Version of the specification format. Currently 1
studentProfile string Yes ID of the student profile, which defines school level, language, etc.
questionMode string Yes "ONE_BY_ONE" to show one question at a time, or "ALL_AT_ONCE" to show all questions
symbols array Yes List of mathematical symbols used in the exercise
elements array Yes List of elements that make up the exercise
script string No Script in Algebrakit syntax for generating randomised instances
settings object No Exercise-level settings that provide defaults for all interactions

Exercise Settings

The optional settings object contains defaults that apply to all interactions in the exercise. Any setting can be overridden on a per-interaction basis using the interaction's own settings object.

Property Type Required Description
angleUnit string No "degrees" or "radians". If not set, the default from the student profile will be used.
allowCalculator boolean No Whether the student may use a calculator. Defaults to true
formulaEditor string No The formula editor layout. One of: automatic, advanced, equations, algebra, arithmetic, chemistry. Defaults to advanced

Symbols

Each symbol defines a mathematical variable, constant, or function used in the exercise.

Property Type Required Description
name string Yes LaTeX notation of the symbol, e.g. "x", "\\angle A_{1}"
type string Yes One of VARIABLE, CONSTANT, FUNCTION, FREEVARIABLE, NAMED_VECTOR
synonym string No Disambiguator when the same symbol has multiple interpretations. For example, m can represent both a variable and a unit (meter). In that case, you must define a different symbol name for each type (e.g., "mMass" and "mMeter") which you will use in the exercise specification and use synonym to indicate that the symbols show as m to students.
addToFormulaEditor boolean No Whether to add the symbol as a button in the formula editor
notations string[] No Alternative notations, e.g. line segment "AB" can also be "BA"

Example:

"symbols": [
  { "name": "x", "type": "VARIABLE" },
  { "name": "\\pi", "type": "CONSTANT" },
  { "name": "f", "type": "FUNCTION" },
  { "name": "total\\ price", "type": "VARIABLE" },
  { "name": "mMass", "type": "UNIT", "synonym": "m" },
  { "name": "mMeter", "type": "VARIABLE", "synonym": "m" },

]

Elements and Blocks

An exercise consists of one or more elements. Each element has an array of blocks stacked vertically. Elements that contain interaction blocks are shown as question blocks with labels a, b, c, etc.

Each block is one of:

Content Block

A static content block displaying text and math.

Property Type Required Description
type string Yes Must be "CONTENT"
content string Yes HTML content with LaTeX in <latex>...</latex> tags

Example:

{
  "type": "CONTENT",
  "content": "Calculate <latex>x</latex> if <latex>2x + 3 = 7</latex>."
}

Interaction Block

An interactive block containing a question for the student.

Property Type Required Description
type string Yes Must be "INTERACTION"
interaction object Yes One of the interaction types described below

Interaction Types

All interaction types share the following properties:

Property Type Required Description
type string Yes The interaction type identifier
refId string No Reference ID for this interaction. Auto-generated if omitted
instruction string No Instruction or question prompt
scored boolean No Whether this interaction is scored. Defaults to true
hints string[] No General hints shown before any attempt is made
settings object No Interaction-level settings that override the exercise defaults for this interaction

Interaction Settings

Each interaction can define its own settings object to override the corresponding exercise-level defaults.

Property Type Required Description
angleUnit string No "degrees" or "radians". Overrides the exercise default
allowCalculator boolean No Whether the student may use a calculator. Overrides the exercise default
formulaEditor string No The formula editor layout: automatic, advanced, equations, algebra, arithmetic, chemistry. Overrides the exercise default

If a setting is omitted at the interaction level, the exercise-level value is used. If it is also omitted at the exercise level, the system default applies.

The supported interaction types are:

Type Description
CHOICE Multiple choice question
FILL_IN_THE_BLANKS Text with blank fields for the student to fill in
MULTISTEP Algebraic multi-step problem with given information, intermediate steps, and a solution
MATH_TABLE Table-based question

CHOICE

A multiple choice question with predefined answer options.

Additional properties:

Property Type Required Description
spec.options array Yes Array of choice options (see below)
spec.shuffle boolean Yes Whether to randomize the order of options
spec.multipleSelect boolean Yes Whether the student can select multiple options

Each option has:

Property Type Required Description
content string Yes HTML content with LaTeX in <latex>...</latex> tags
correct boolean Yes Whether this option is correct

Example:

{
  "type": "CHOICE",
  "instruction": "Which of the following is a prime number?",
  "spec": {
    "shuffle": true,
    "multipleSelect": false,
    "options": [
      { "content": "<latex>7</latex>", "correct": true },
      { "content": "<latex>9</latex>", "correct": false },
      { "content": "<latex>15</latex>", "correct": false }
    ]
  }
}

FILL_IN_THE_BLANKS

A question where the student fills in blanks within a content string.

Additional properties:

Property Type Required Description
content string Yes HTML with <blank id="..."></blank> placeholders
blanks array Yes Array of blank specifications (see below)
interchangables string[][] No Groups of blank IDs whose answers are interchangeable, e.g. [["B1", "B2"]]

Each blank has:

Property Type Required Description
id string Yes Unique ID matching a <blank> placeholder in the content
size string Yes Display size: SMALL, MEDIUM, or LARGE
type string Yes EXPRESSION for a math input, or SELECTION for a dropdown choice
input object Yes Either an expression input or a selection input

Expression Input

Used when type is EXPRESSION. The student enters a mathematical expression.

Property Type Required Description
task object Conditional A task specification defining what the student must calculate. Required unless criteria is provided
criteria object Conditional An evaluation criteria set defining how to evaluate the student's input. Required unless task is provided
unit object No Unit specification for the expected answer
accuracy object No Accuracy specification for evaluating the answer
form object No Form specification for the expected form of the answer

Selection Input

Used when type is SELECTION. The student picks from a dropdown.

Property Type Required Description
options array Yes Array of options, each with content (string) and correct (boolean)
shuffle boolean Yes Whether to randomize options
multipleSelect boolean Yes Whether multiple selections are allowed

Example:

{
  "type": "FILL_IN_THE_BLANKS",
  "content": "Calculate <latex>\\sqrt{x^2}</latex> = <blank id=\"B1\"></blank>.",
  "blanks": [
    {
      "id": "B1",
      "size": "MEDIUM",
      "type": "EXPRESSION",
      "input": {
        "task": {
          "type": "SIMPLIFY",
          "expression": "\\sqrt{x^2}"
        }
      }
    }
  ]
}

MULTISTEP

An algebraic multi-step problem. This is the most common interaction type for algebra exercises. It consists of optional given information, optional intermediate steps, and a required solution part.

Additional properties:

Property Type Required Description
givenParts object No Given information provided to the student. Keys are labels like "G1", "G2"
intermediateParts object No Intermediate calculations the student must perform. Keys are labels like "S1", "S2"
solutionPart object Yes The final calculation the student must complete
initialExpressionType string No Specifies whether an initial expression is shown to the student. One of "AUTOMATIC", "NONE", or "CUSTOM". Default is "AUTOMATIC" if no intermediate parts are defined, "NONE" otherwise
initialExpression string No A custom initial expression in LaTeX, used when initialExpressionType is "CUSTOM"

Each part (given, intermediate, or solution) has:

Property Type Required Description
task object Conditional A task specification defining the calculation. Required unless criteria is provided
criteria object Conditional An evaluation criteria set defining how to evaluate the student's input. Required unless task is provided
unit object No Unit specification for the expected answer
accuracy object No Accuracy specification for evaluating the answer
form object No Form specification for the expected form of the answer
symbol string No A variable or function that represents this part, e.g. "E" for energy or "f(x)" for a function definition
description string No A description of what this part represents, e.g. "the total discount"
alternativeTasks array No Array of alternative task specifications that are also accepted as correct answers for this part. Only applicable when task is used

Parts in givenParts and intermediateParts can reference each other's labels in their expressions.

Example:

{
  "type": "MULTISTEP",
  "instruction": "Solve the following equation for x.",
  "solutionPart": {
    "task": {
      "type": "SOLVE",
      "expression": "2x + 3 = 7",
      "variable": "x"
    }
  }
}

Example with given and intermediate parts:

{
  "type": "MULTISTEP",
  "instruction": "A circle has an area of <latex>12 m^2</latex>. Calculate the radius.",
  "givenParts": {
    "G1": {
      "task": { "type": "SIMPLIFY", "expression": "12" },
      "description": "the area of the circle"
    },
  },
  "solutionPart": {
    "task": { "type": "SOLVE", "expression": "r^2=G1", "variable": "r", "domain": "r\\geq 0" },
    "description": "the area of the circle"
  }
}

MATH_TABLE

A table-based question where the student fills in cells of a mathematical table.

Additional properties:

Property Type Required Description
cells array Yes Array of cell specifications (see below)

Each cell has:

Property Type Required Description
type string Yes "text" for plain text, "math" for a mathematical expression, or "input" for an input field
row number Yes Row index. Header row is 0, data rows start from 1
col number Yes Column index. Header column is 0, data columns start from 1
isHeader boolean Yes Whether this cell is a header cell
content string No Text content, applicable for text cells. Embed LaTeX expressions between <latex>..</latex>.
value string No Mathematical expression in LaTeX, applicable for math cells
spec object No An expression input specification defining the expected answer, applicable for input cells

Example:

{
  "type": "MATH_TABLE",
  "instruction": "Complete the multiplication table.",
  "cells": [
    { "type": "text", "row": 0, "col": 0, "isHeader": true, "content": "<latex>\\times</latex>" },
    { "type": "math", "row": 0, "col": 1, "isHeader": true, "value": "2" },
    { "type": "math", "row": 0, "col": 2, "isHeader": true, "value": "3" },
    { "type": "math", "row": 1, "col": 0, "isHeader": true, "value": "4" },
    { "type": "input", "row": 1, "col": 1, "isHeader": false, "spec": {
      "task": { "type": "SIMPLIFY", "expression": "2\\times 4" }
    }},
    { "type": "input", "row": 1, "col": 2, "isHeader": false, "spec": {
      "task": { "type": "SIMPLIFY", "expression": "3\\times 4" }
    }}
  ]
}

Task Types

A task defines what calculation the student needs to perform. Tasks are used within MULTISTEP and FILL_IN_THE_BLANKS interactions. All expressions are written in LaTeX notation.

Task Type Description Required Properties
SIMPLIFY Simplify a mathematical expression expression
SOLVE Solve an equation or inequality for a variable expression, variable
SOLVE_SYSTEM Solve a system of equations expression, variables
EXPAND Expand an expression (multiply out brackets) expression
FACTOR Factor an expression expression
TOGETHER Combine a sum of fractions into a single fraction expression
COMPLETE_SQUARE Complete the square for a quadratic expression, variable
POLYNOMIAL_STANDARD_FORM Convert to polynomial standard form expression, variable
POWER_STANDARD_FORM Rewrite radicals and fractions into exponent form expression, variable
EXPONENTIAL_STANDARD_FORM Convert to exponential standard form b⋅gxb \cdot g^x expression, variable
CARTESIAN_TO_POLAR_FORM Convert Cartesian to polar coordinates expression
POLAR_TO_CARTESIAN_FORM Convert polar to Cartesian coordinates expression

Common Task Properties

All task types have:

Property Type Required Description
type string Yes The task type (see table above)
expression string Yes LaTeX expression, e.g. "x^2 - 4 = 0"

Task-Specific Properties

SOLVE:

Property Type Required Description
variable string Yes Variable to solve for, e.g. "x"
domain string No Domain restriction as an inequality, e.g. "x \\geq 0"

SOLVE_SYSTEM:

Property Type Required Description
variables string[] Yes Variables to solve for, e.g. ["x", "y"]
expression string Yes System as a LaTeX set, e.g. "\\{x+y=1, x-y=2\\}"
domain string No Domain restriction
restrictVariable string No If given, only solve for this variable
method string No Solving method: Eliminate, Substitute, or Equate

COMPLETE_SQUARE, POLYNOMIAL_STANDARD_FORM, POWER_STANDARD_FORM, EXPONENTIAL_STANDARD_FORM:

Property Type Required Description
variable string Yes The variable, e.g. "x"

Task Examples

{ "type": "SIMPLIFY", "expression": "3x + 2x" }
{ "type": "SOLVE", "expression": "x^2 - 4 = 0", "variable": "x" }
{
  "type": "SOLVE_SYSTEM",
  "expression": "\\{x + y = 5, 2x - y = 1\\}",
  "variables": ["x", "y"],
  "method": "Substitute"
}
{ "type": "FACTOR", "expression": "x^2 - 9" }

Unit

An optional unit specification defines the expected unit for the student's answer.

Property Type Required Description
unit string Yes The expected unit in LaTeX notation, e.g. "\\frac{m}{s}" or "kg"
allowEquivalentUnits boolean No Whether to accept equivalent units (e.g. m and km). Defaults to false
override boolean No Whether to override the unit inferred from the task. Defaults to false

Example:

{
  "task": {
    "type": "SIMPLIFY",
    "expression": "100 \\cdot \\frac{1000}{3600}"
  },
  "unit": { "unit": "\\frac{m}{s}" }
}

Accuracy

An optional accuracy specification defines how the student's numerical answer is evaluated.

Property Type Required Description
type string Yes ROUND, ROUND_UP, ROUND_DOWN, ACCURATE, or PRECISION
nr number Yes Number of decimal places or significant digits
keepDecimalZeros boolean No Whether to keep trailing zeros in decimal answers. If true, answers must have exactly nr decimal places, even if that means trailing zeros. Applies to all types except PRECISION. Defaults to false

Example:

{
  "task": {
    "type": "SIMPLIFY",
    "expression": "\\frac{1}{3}"
  },
  "accuracy": { "type": "ROUND", "nr": 2 }
}

Form

An optional form specification defines the expected form of the student's answer. It allows specifying preferences or requirements for how numbers, radicals, and fractions should be presented.

Property Type Required Description
numbers string No How numbers should be presented. See number options below
radicals string No How radicals should be presented. Currently only STANDARD_FORM_REQUIRED
fractions string No How fractions should be presented. See fraction options below

Number Options

Value Description
DECIMAL_REQUIRED The answer must be written as a decimal
DECIMAL_PREFERRED A decimal answer is preferred but not required
FRACTION_REQUIRED The answer must be written as a fraction
FRACTION_PREFERRED A fraction answer is preferred but not required
SCIENTIFIC_NOTATION_REQUIRED The answer must be in scientific notation
SCIENTIFIC_NOTATION_PREFERRED Scientific notation is preferred but not required

Fraction Options

Value Description
MIXED_FRACTION_REQUIRED The answer must be written as a mixed fraction (e.g. 1121\frac{1}{2})
IMPROPER_FRACTION_REQUIRED The answer must be written as an improper fraction (e.g. 32\frac{3}{2})

Example:

{
  "task": {
    "type": "SIMPLIFY",
    "expression": "\\sqrt{8}"
  },
  "form": { "radicals": "STANDARD_FORM_REQUIRED" }
}
{
  "task": {
    "type": "SIMPLIFY",
    "expression": "\\frac{1}{3} + \\frac{1}{2}"
  },
  "form": { "numbers": "DECIMAL_REQUIRED" },
  "accuracy": { "type": "ROUND", "nr": 2 }
}

Evaluation Criteria

Evaluation criteria define how the student's input is evaluated step by step. It is an alternative to the automated evaluations of tasks. The rules are evaluated in order until one matches. If none match, the input will be matched against the task, if defined. If no task is defined and no rules match, the otherwise result and otherwiseMessage are used.

The criteria object has the following structure:

Property Type Required Description
rules array Yes Ordered list of evaluation rules. Evaluated in order until one matches
otherwise string Yes The fallback result when none of the rules match and no task is defined. One of: FINISHED, ERROR, UNKNOWN. Cannot be INTERMEDIATE
otherwiseMessage string No Optional fallback message shown to the student when none of the rules match and no task is defined

Evaluation Rule Properties

Each rule in the rules array has:

Property Type Required Description
result string Yes The result when this rule is satisfied. See rule types below
type string Yes The type of test to apply. See rule types below
expressions string[] Yes Mathematical expressions to evaluate against the student's input, written in LaTeX notation
inputVariable string No The name of the variable representing the student's input to evaluate, e.g. "input". Required when type is MATCH_CONDITION or NOT_MATCH_CONDITION
solveFor string No Optional variable to solve for, e.g. "x". Only used when type is EQUAL_EQUIVALENT or NOT_EQUAL_EQUIVALENT
message string No Optional hint or feedback message shown to the student when this rule matches. Wrap math expressions in <latex>...</latex> tags.
rounding object No Accuracy specification for evaluating the student's answer
tags array No Array of skill tags, each with id (string) and optional errorIds (string[])

Rule Results

The evaluation result must be one of the following four options:

Value Description
FINISHED The student's input is a correct final answer.
INTERMEDIATE The student's input is a correct intermediate step. Use message to define a hint.
ERROR The student's input is an incorrect step. Use message to define error feedback.
UNKNOWN Indicates that it is unclear whether the input is correct or wrong.

Rule Test Types

The type determines how the student's input is compared against the expressions:

Value Description
EQUAL_EXACT The student's input must match exactly (text-based comparison)
EQUAL_COMMUTATIVE The student's input must be algebraically equal, respecting commutativity
EQUAL_EQUIVALENT The student's input must be algebraically equivalent
MATCH_CONDITION The student's input must satisfy the given mathematical conditions. Requires inputVariable
NOT_EQUAL_EXACT The student's input must NOT match exactly
NOT_EQUAL_COMMUTATIVE The student's input must NOT be algebraically equal
NOT_EQUAL_EQUIVALENT The student's input must NOT be algebraically equivalent
NOT_MATCH_CONDITION The student's input must NOT satisfy the given conditions. Requires inputVariable
ANY_INPUT Any input is accepted

Example of a multistep interaction using criteria:

{
  "type": "MULTISTEP",
  "instruction": "Write a divisor of 18",
  "solutionPart": {
    "criteria": {
      "rules": [
        {
          "result": "FINISHED",
          "type": "MATCH_CONDITION",
          "expressions": ["\\frac{val}{18}\\in\\mathbb{Z}" ],
          "inputVariable": "val",
          "tags": []
        }
      ],
      "otherwise": "ERROR",
      "otherwiseMessage": "That's not correct. Try again."
    }
  }
}

Complete Example

An exercise with a content block followed by two questions: a fill-in-the-blanks and a multistep interaction.

{
  "type": "AK_Exercise",
  "version": 1,
  "studentProfile": "your-profile-id",
  "questionMode": "ALL_AT_ONCE",
  "symbols": [
    { "name": "x", "type": "VARIABLE" },
    { "name": "y", "type": "VARIABLE" }
  ],
  "elements": [
    {
      "blocks": [
        {
          "type": "CONTENT",
          "content": "<b>Exercise</b>: Work with the equation <latex>2x + 3 = 7</latex>."
        },
        {
          "type": "INTERACTION",
          "interaction": {
            "type": "FILL_IN_THE_BLANKS",
            "instruction": "Fill in the missing values.",
            "content": "If <latex>2x + 3 = 7</latex>, then <latex>2x =</latex> <blank id=\"B1\"></blank>",
            "blanks": [
              {
                "id": "B1",
                "size": "SMALL",
                "type": "EXPRESSION",
                "input": {
                  "task": { "type": "SIMPLIFY", "expression": "4" }
                }
              }
            ]
          }
        }
      ]
    },
    {
      "blocks": [
        {
          "type": "INTERACTION",
          "interaction": {
            "type": "MULTISTEP",
            "instruction": "Now solve for x.",
            "solutionPart": {
              "task": {
                "type": "SOLVE",
                "expression": "2x + 3 = 7",
                "variable": "x"
              }
            }
          }
        }
      ]
    }
  ]
}

Tips and Tricks

LaTeX notation of math expression

If in doubt how to encode a math expression in LaTex, create the expression using Algebrakit's formula editor and use copy-paste to obtain the LaTeX notation.