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

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`	string	No	Unit associated with the expression
`accuracy`	object	No	Accuracy specification for evaluating 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

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

Property	Type	Required	Description
`task`	object	Yes	A task specification defining the calculation
`unit`	string	No	Unit associated with the expression
`accuracy`	object	No	Accuracy specification for evaluating the answer

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": "Given the area and width, calculate the length.",
  "givenParts": {
    "G1": {
      "task": { "type": "SIMPLIFY", "expression": "24" }
    },
    "G2": {
      "task": { "type": "SIMPLIFY", "expression": "6" }
    }
  },
  "intermediateParts": {
    "S1": {
      "task": { "type": "SIMPLIFY", "expression": "\\frac{G1}{G2}" }
    }
  },
  "solutionPart": {
    "task": { "type": "SIMPLIFY", "expression": "S1" }
  }
}

MATH_TABLE

A table-based question. The MATH_TABLE interaction uses only the common interaction properties.

Example:

{
  "type": "MATH_TABLE",
  "instruction": "Complete the multiplication table."
}

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

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

Example:

{
  "task": {
    "type": "SIMPLIFY",
    "expression": "\\frac{1}{3}"
  },
  "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"
              }
            }
          }
        }
      ]
    }
  ]
}