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

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`
`synonym`	string	No	Disambiguator when a symbol has multiple interpretations, e.g. `"mMass"` vs `"mMeter"`
`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" }
]

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
`enableCalculator`	boolean	No	Whether to enable a calculator for this interaction. Defaults to `true`

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	Yes	A task specification defining what the student must calculate
`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	Yes	A task specification defining the calculation
`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

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 \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. $1\frac{1}{2}$ )
`IMPROPER_FRACTION_REQUIRED`	The answer must be written as an improper fraction (e.g. $\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 }
}

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"
              }
            }
          }
        }
      ]
    }
  ]
}