Numbas exam schema v8.1

Numbas .exam files are JSON objects, with an additional comment line at the start describing the version of the format used.

The line for the current version should look like this:

// Numbas version: finer_feedback_settings

The rest of the file should consist of a single JSON object, matching the following schema.

Download the schema in JSON-Schema format

Numbas Exam

object

allowPrinting

boolean

Allow students to print question content?
contributors

Contributors to this item
custom_part_types
array

Custom part types used in this exam
Items:
object

can_be_gap

boolean

Can this part type be a gap?

can_be_step

boolean

Can this part type be a step?

title

HTML code

Description

extensions

array

Extensions required by this part type

Items:

string

The name of an extension

help_url

string

URL of a help page

input_options

object

Options for the input widget

input_widget

string

The input widget used by this part type

marking_notes

array

Marking notes

marking_script

JME notes

Marking script

name

string

Name

settings

array

Definitions of settings for the part type

short_name

string

A globally unique short name

source

object

Information about the source of this custom part type

author

object

Author

name

string

Name

pk

number

ID

edit_page

string

URL of the page to edit the custom part type

pk

number

ID
diagnostic
object

Diagnostic mode settings
- customScript
  
  JME notes
  
  Custom diagnostic algorithm
- knowledge_graph
  object
  
  Knowledge graph
  
  learning_objectives
  
  array
  
  Learning objectives
  
  Items:
  
  object
  
  title
  
  HTML code
  
  Description
  
  name
  
  string
  
  Name
  
  topics
  
  array
  
  Topics
  
  Items:
  
  object
  
  depends_on
  
  array
  
  Names of topics this topic depends on
  
  Items:
  
  string
  
  title
  
  HTML code
  
  Description
  
  learning_objectives
  
  array
  
  Names of learning objectives this topic belongs to
  
  Items:
  
  string
  
  name
  
  string
  
  Name
- script
  string
  
  Diagnostic algorithm
  
  Must be one of:
  
  "diagnosys"
  
  "mastery"
  
  "custom"
duration

number

The duration of the exam, in seconds
extensions

array

Extensions required by this exam

Items:

string

The name of an extension
feedback
object

Feedback settings
- results_options
  object
  
  Results page options
  
  printquestions
  
  boolean
  
  Show questions in printed results summary?
  
  printadvice
  
  boolean
  
  Show advice in printed results summary?
- allowrevealanswer
  
  boolean
  
  Allow reveal answer?
- feedbackmessages
  array
  
  Feedback messages
  
  Items:
  
  object
  
  message
  
  string
  
  Message
  
  threshold
  
  number
  
  Percentage score (0-100) above which this message is shown.
- intro
  
  string
  
  Introduction
- showadvicewhen
  string
  
  When to show question advice
  
  Must be one of:
  
  "inreview"
  
  "never"
- showexpectedanswerswhen
  string
  
  When to reveal expected answers
  
  Must be one of:
  
  "inreview"
  
  "never"
- showactualmarkwhen
  string
  
  When to show the current score
  
  Must be one of:
  
  "always"
  
  "oncompletion"
  
  "inreview"
  
  "never"
- showanswerstatewhen
  string
  
  When to show answer state
  
  Must be one of:
  
  "always"
  
  "oncompletion"
  
  "inreview"
  
  "never"
- showtotalmarkwhen
  string
  
  When to show the maximum score
  
  Must be one of:
  
  "always"
  
  "oncompletion"
  
  "inreview"
  
  "never"
- showpartfeedbackmessageswhen
  string
  
  When to show part feedback messages
  
  Must be one of:
  
  "always"
  
  "oncompletion"
  
  "inreview"
  
  "never"
metadata

Item metadata
name

string

The name of the exam
navigation
object

Navigation settings
- allowregen
  
  boolean
  
  Allow user to regenerate questions?
- allowsteps
  
  boolean
  
  Enable steps?
- browse
  
  boolean
  
  Allow jump to any question?
- navigatemode
  string
  
  Question navigation mode
  
  Must be one of:
  
  "sequence"
  
  "menu"
  
  "diagnostic"
- onleave
  object
  
  On leaving a question
  
  action
  
  string
  
  Action
  
  Must be one of:
  
  "none"
  
  "warnifunattempted"
  
  "preventifunattempted"
  
  message
  
  string
  
  Message
- preventleave
  
  boolean
  
  Confirm before leaving the exam while it's running?
- typeendtoleave
  
  boolean
  
  Require written confirmation before leaving the exam
- reverse
  
  boolean
  
  Allow move to previous question?
- showfrontpage
  
  boolean
  
  Show front page?
- enterreviewmodeimmediately
  
  boolean
  
  Enter review mode immediately after ending the exam?
- startpassword
  
  string
  
  Password to begin the exam
- allowAttemptDownload
  
  boolean
  
  Allow the student to download their attempt data?
- downloadEncryptionKey
  
  string
  
  Key for encrypting student data downloads
- autoSubmit
  
  boolean
  
  Automatically submit answers?
percentPass

JME code

The pass/fail threshold for the student's total score, as a percentage of the available marks.
question_groups
array

Question groups
Items:
object

name

string

Name

pickQuestions

JME code

Number of questions to choose

pickingStrategy

string

Questions to use

Must be one of:

"all-ordered"

"all-shuffled"

"random-subset"

questionNames

array

Override question names

Items:

string

questions

array

Question definitions

Items:

Question

variable_overrides

array

Variable overrides. One item for each question in the group.

Items:

object

definition

JME code

Variable definition

name

string

The name of the variable to override
resources
array

Resource files associated with the exam
Items:
array

A tuple:

string

Name

string

Path
showQuestionGroupNames

boolean

Should the names of question groups be shown to the student?
showstudentname

boolean

Show the student's name?
shuffleQuestionGroups

boolean

If true, the question groups appear in random order.
timing
object

Timing settings
- allowPause
  
  boolean
  
  Allow pausing?
- timedwarning
  object
  
  5 minutes before timeout
  
  action
  
  string
  
  Action
  
  Must be one of:
  
  "none"
  
  "warn"
  
  message
  
  string
  
  Message
- timeout
  object
  
  On timeout
  
  action
  
  string
  
  Action
  
  Must be one of:
  
  "none"
  
  "warn"
  
  message
  
  string
  
  Message

Subschemas

Contributors to this item
array
Items:
object

name

string

The contributor's name

profile_url

string

Profile URL on the Numbas editor
HTML code

string
Item metadata
object
- title
  
  HTML code
  
  A description of the item.
- licence
  
  string
  
  The licence under which the item is distributed.
The path to a question part

string
Custom part type settings

object
LaTeX code

string
JME notes

string
JME code
One of

Option 1

string

Option 2

number
Question
object
- advice
  
  HTML code
  
  Advice
- builtin_constants
  
  object
  
  Which built-in constants are enabled
  
  Additional properties
  
  boolean
- constants
  array
  
  Constants
  
  Items:
  
  object
  
  name
  
  string
  
  Name
  
  tex
  
  LaTeX code
  
  LaTeX rendering
  
  value
  
  JME code
  
  JME value
- extensions
  
  array
  
  Extensions required by this question
  
  Items:
  
  string
  
  The name of an extension
- metadata
  
  Item metadata
- name
  
  string
  
  Name
- rulesets
  
  object
  
  Rulesets
  
  Additional properties
  
  array
  
  Items:
  
  string
- statement
  
  HTML code
  
  Statement
- tags
  
  array
  
  Tags
  
  Items:
  
  string
- variables
  object
  
  Variable definitions
  
  Additional properties
  
  object
  
  can_override
  
  boolean
  
  Can an exam override the value of this variable?
  
  definition
  
  JME code
  
  Definition
  
  description
  
  HTML code
  
  Description
  
  group
  
  Group
  
  One of
  
  Option 1
  
  string
  
  Option 2
  
  null
  
  name
  
  string
  
  Name, or comma-separated list of names
  
  templateType
  
  string
  
  Data type template
  
  Must be one of:
  
  "anything"
  
  "number"
  
  "range"
  
  "randrange"
  
  "string"
  
  "long plain string"
  
  "long string"
  
  "list of numbers"
  
  "list of strings"
  
  "json"
- variablesTest
  object
  
  Variable testing
  
  condition
  
  string
  
  Condition
  
  maxRuns
  
  JME code
  
  Maximum number of runs
- ungrouped_variables
  
  array
  
  Names of ungrouped variables
  
  Items:
  
  string
- variable_groups
  array
  
  Variable groups
  
  Items:
  
  object
  
  name
  
  string
  
  Name
  
  variables
  
  array
  
  Variables
  
  Items:
  
  string
- functions
  object
  
  Functions
  
  Additional properties
  
  object
  
  parameters
  
  array
  
  Parameters
  
  Items:
  
  object
  
  name
  
  string
  
  Name
  
  type
  
  string
  
  Type signature
  
  type
  
  string
  
  Type
  
  language
  
  string
  
  Language
  
  Must be one of:
  
  "jme"
  
  "javascript"
  
  definition
  
  string
  
  Definition
- preamble
  object
  
  Preamble
  
  js
  
  string
  
  JavaScript preamble
  
  css
  
  string
  
  CSS preamble
- parts
  
  array
  
  Parts
  
  Items:
  
  Part
- partsMode
  string
  
  Parts mode
  
  Must be one of:
  
  "all"
  
  "explore"
- maxMarks
  
  JME code
  
  Maximum mark
- objectives
  
  array
  
  Objectives
  
  Items:
  
  Score bin
- penalties
  
  array
  
  Penalties
  
  Items:
  
  Score bin
- objectiveVisibility
  string
  
  Show objectives
  
  Must be one of:
  
  "always"
  
  "when-active"
- penaltyVisibility
  string
  
  Show penalties
  
  Must be one of:
  
  "always"
  
  "when-active"
Score bin
object
- name
  
  string
  
  Name
- limit
  
  JME code
  
  Limit
Part
object
Any of

Option 1

Gap-fill

type

string
= "gapfill"

gaps

array

Gaps

Items:

Part

sortAnswers

boolean

Sort student's answers before marking?

Option 2

Information only

type

string
= "information"

Option 3

Extension

type

string
= "extension"

Option 4

Mathematical expression

type

string
= "jme"

answer

JME code

Expected answer

showPreview

boolean

Show preview of student's answer?

checkingType

string

Checking type

Must be one of:

"absdiff"

"reldiff"

"dp"

"sigfig"

checkingAccuracy

number

Checking accuracy

failureRate

number

Maximum no. of failures

vsetRangePoints

number

Points to check

vsetRange

array

Checking range

A tuple:

number

Start

number

End

checkVariableNames

boolean

Warn if student uses an unexpected variable name?

singleLetterVariables

boolean

Force single letter variable names?

allowUnknownFunctions

boolean

Allow unknown function names?

implicitFunctionComposition

boolean

Use implicit function composition?

caseSensitive

boolean

Expression is case-sensitive?

maxlength

object

Maximum length restriction

length

number

Maximum length

partialCredit

number

Partial credit for long answer

message

HTML code

Warning message

minlength

object

Minimum length restriction

length

number

Minimum length

partialCredit

number

Partial credit for short answer

message

HTML code

Warning message

musthave

object

Required strings

strings

array

Required strings

Items:

string

showStrings

boolean

Show required strings?

partialCredit

number

Partial credit for not using all required strings

message

HTML code

Warning message

notallowed

object

Forbidden strings

strings

array

Forbidden strings

Items:

string

showStrings

boolean

Show forbidden strings?

partialCredit

number

Partial credit for using any forbidden string

message

HTML code

Warning message

mustmatchpattern

object

Pattern student's answer must match

pattern

JME code

Pattern student's answer must match

partialCredit

number

Partial credit for not matching pattern

message

HTML code

Warning message

nameToCompare

string

Part of expression to mark

valuegenerators

array

Variable value generators

Items:

object

name

string

Name

value

JME code

Value generator

Option 5

Number entry

type

string
= "numberentry"

minValue

JME code

Minimum accepted value

maxValue

JME code

Maximum accepted value

correctAnswerFraction

boolean

Display the correct answer as a fraction?

allowFractions

boolean

Allow the student to enter a fraction?

mustBeReduced

boolean

Must the fraction be reduced?

mustBeReducedPC

JME code

Partial credit for unreduced fraction

precisionType

string

Precision restriction

Must be one of:

"none"

"dp"

"sigfig"

precision

JME code

Precision

precisionPartialCredit

number

Partial credit for wrong precision

strictPrecision

boolean

Require trailing zeros?

showPrecisionHint

boolean

Show precision restriction hint?

showFractionHint

boolean

Show fraction input hint?

notationStyles

array

Allowed notation

Items:

string

correctAnswerStyle

string

Correct answer style

displayAnswer

JME code

The value to be displayed as the expected answer

Option 6

Matrix entry

type

string
= "matrix"

correctAnswer

JME code

Correct answer

correctAnswerFractions

boolean

Display numbers in the correct answer as fractions?

numRows

JME code

Number of rows

numColumns

JME code

Number of columns

allowResize

boolean

Allow student to change size of matrix?

tolerance

JME code

Margin of error allowed in each cell

markPerCell

boolean

Gain marks for each correct cell?

allowFractions

boolean

Allow the student to enter fractions?

minColumns

JME code

Minimum number of columns

maxColumns

JME code

Maximum number of columns

minRows

JME code

Minimum number of rows

maxRows

JME code

Maximum number of rows

precisionType

string

Precision restriction

Must be one of:

"none"

"dp"

"sigfig"

precision

JME code

Precision

precisionPartialCredit

number

Partial credit for wrong precision

strictPrecision

boolean

Require trailing zeros?

Option 7

Match text pattern

type

string
= "patternmatch"

answer

string

Answer pattern

displayAnswer

string

Display answer

caseSensitive

boolean

Must the answer be in the correct case?

partialCredit

number

Partial credit for answer not matching case

matchMode

string

Match test

Must be one of:

"regex"

"exact"

Option 8

Choose one from a list

type

string
= "1_n_2"

shuffleChoices

boolean

Shuffle order of choices?

displayType

string

Selection type

Must be one of:

"radiogroup"

"dropdownlist"

displayColumns

JME code

Number of display columns

showCellAnswerState

boolean

Show choice feedback state?

choices

Choices

One of

Option 1

JME code

Option 2

array

Items:

HTML code

matrix

Marking matrix

One of

Option 1

JME code

Option 2

array

Items:

JME code

distractors

array

Distractors

Items:

HTML code

Option 9

Choose several from a list

type

string
= "m_n_2"

minMarks

JME code

Minimum marks

maxMarks

JME code

Maximum marks

shuffleChoices

boolean

Shuffle order of choices?

displayType

string

Selection type
= "checkbox"

displayColumns

JME code

Number of display columns

minAnswers

JME code

Minimum answers

maxAnswers

JME code

Maximum answers

warningType

string

What to do if wrong number of answers selected

Must be one of:

"none"

"warn"

"prevent"

showCellAnswerState

boolean

Show choice feedback state?

markingMethod

string

Marking method

Must be one of:

"sum ticked cells"

"score per matched cell"

"all-or-nothing"

choices

Choices

One of

Option 1

JME code

Option 2

array

Items:

HTML code

matrix

Marking matrix

One of

Option 1

JME code

Option 2

array

Items:

JME code

distractors

array

Distractors

Items:

HTML code

Option 10

Match choices with answers

type

string
= "m_n_x"

minMarks

JME code

Minimum marks

maxMarks

JME code

Maximum marks

shuffleChoices

boolean

Shuffle order of choices?

shuffleAnswers

boolean

Shuffle order of answers?

displayType

string

Selection type

Must be one of:

"radiogroup"

"checkbox"

displayColumns

JME code

Number of display columns

minAnswers

JME code

Minimum answers

maxAnswers

JME code

Maximum answers

warningType

string

What to do if wrong number of answers selected

Must be one of:

"none"

"warn"

"prevent"

showCellAnswerState

boolean

Show choice feedback state?

markingMethod

string

Marking method

Must be one of:

"sum ticked cells"

"score per matched cell"

"all-or-nothing"

choices

Choices

One of

Option 1

JME code

Option 2

array

Items:

HTML code

answers

Answers

One of

Option 1

JME code

Option 2

array

Items:

HTML code

matrix

Marking matrix

One of

Option 1

JME code

Option 2

array

Items:

JME code

layout

object

Layout

name

string

Layout type

Must be one of:

"all"

"lowertriangle"

"strictlowertriangle"

"uppertriangle"

"strictuppertriangle"

"expression"

expression

JME code

Custom layout expression

Option 11

Custom

type

string

settings

Custom part type settings

Settings
- useCustomName
  
  boolean
  
  Use a custom name?
- customName
  
  string
  
  Custom name
- marks
  
  JME code
  
  Marks
- scripts
  object
  
  Custom JavaScript
  
  constructor
  
  object
  
  When the part is created
  
  script
  
  string
  
  Script
  
  order
  
  string
  = "after"
  
  mark
  
  object
  
  Mark student's answer
  
  script
  
  string
  
  Script
  
  order
  
  string
  
  This script runs...
  
  Must be one of:
  
  "instead of"
  
  "after"
  
  "before"
  
  validate
  
  object
  
  Validate student's answer
  
  script
  
  string
  
  Script
  
  order
  
  string
  
  This script runs...
  
  Must be one of:
  
  "instead of"
  
  "after"
  
  "before"
- customMarkingAlgorithm
  
  string
  
  Custom marking algorithm
- extendBaseMarkingAlgorithm
  
  boolean
  
  Extend base marking algorithm?
- unitTests
  array
  
  Unit tests
  
  Items:
  
  object
  
  variables
  
  array
  
  Variables
  
  Items:
  
  object
  
  name
  
  string
  
  Name
  
  value
  
  JME code
  
  Value
  
  name
  
  string
  
  Name
  
  answer
  
  object
  
  Answer
  
  valid
  
  boolean
  
  Answer is valid?
  
  value
  
  object
  
  Value
  
  notes
  
  array
  
  Notes
  
  Items:
  
  object
  
  name
  
  string
  
  Name
  
  expected
  
  object
  
  Expected values
  
  value
  
  JME code
  
  Value
  
  messages
  
  array
  
  Feedback messages
  
  Items:
  
  string
  
  warnings
  
  array
  
  Warnings
  
  Items:
  
  string
  
  error
  
  string
  
  Error
  
  valid
  
  boolean
  
  Answer is valid?
  
  credit
  
  number
  
  Credit
- showCorrectAnswer
  
  boolean
  
  Show correct answer on reveal?
- showFeedbackIcon
  
  boolean
  
  Show score feedback icon?
- variableReplacements
  array
  
  Variable replacements
  
  Items:
  
  object
  
  variable
  
  string
  
  Variable to replace
  
  part
  
  The path to a question part
  
  Path of the part to use
  
  must_go_first
  
  boolean
  
  Must be answered?
- variableReplacementStrategy
  string
  
  Variable replacement strategy
  
  Must be one of:
  
  "originalfirst"
  
  "alwaysreplace"
- nextParts
  array
  
  Next part options
  
  Items:
  
  object
  
  label
  
  string
  
  Label (`rawLabel`, or the other part's name is used if `rawLabel` is empty)
  
  rawLabel
  
  string
  
  Raw label
  
  otherPart
  
  number
  
  Next part
  
  variableReplacements
  
  array
  
  Variable replacements
  
  Items:
  
  object
  
  variable
  
  string
  
  Variable to replace
  
  definition
  
  JME code
  
  Definition
  
  availabilityCondition
  
  JME code
  
  Availability condition
  
  penalty
  
  string
  
  Penalty to apply when visited
  
  penaltyAmount
  
  JME code
  
  Amount of penalty
  
  lockAfterLeaving
  
  boolean
  
  Lock this part?
- suggestGoingBack
  
  boolean
  
  Suggest going back to the previous part?
- adaptiveMarkingPenalty
  
  JME code
  
  Penalty when adaptive marking is used
- exploreObjective
  Score counts towards objective
  
  One of
  
  Option 1
  
  string
  
  Option 2
  
  null
- prompt
  
  HTML code
  
  Prompt
- stepsPenalty
  
  number
  
  Penalty for revealing steps
- steps
  
  array
  
  Steps
  
  Items:
  
  Part
- alternatives
  
  array
  
  Alternative answers
  
  Items:
  
  Part
- alternativeFeedbackMessage
  
  string
  
  Message if this alternative is used
- useAlternativeFeedback
  
  boolean
  
  Show all feedback?

Numbas Exam

Subschemas

Contributors to this item

HTML code

Item metadata

The path to a question part

Custom part type settings

LaTeX code

JME notes

JME code

Question

Score bin

Part