The Question object

Questions are the core building block of the Examplary platform. The same Question object shape is used everywhere a question appears: in the REST API (creating exams, managing exam questions, and the question bank), in embed session flows, and as the question prop passed to custom question type components.

This guide describes the structure of that object and what each field is for. A machine-readable JSON Schema of the Question object is also available, which you can use to validate questions or generate types in your own system.

Example

{
  "id": "q_qQjXQasmUfpWRV5KO5mzkxoy",
  "v": 3,
  "type": "single-line-text",
  "title": "Napoleon's role in the French Revolution",
  "description": "When Napoleon Bonaparte rose to power, he was seen as a hero of the French Revolution. However, his actions and policies during his rule have been debated by historians. What was Napoleon's role in the French Revolution?",
  "settings": {
    "hintEnabled": true,
    "wordLimit": 200
  },
  "scoring": {
    "rubricType": "analytical",
    "criteria": [
      {
        "id": "c1",
        "title": "Correctness",
        "levels": [
          { "id": "c1l1", "title": "Correct", "points": 1 },
          { "id": "c1l2", "title": "Partially correct", "points": 0.5 },
          { "id": "c1l3", "title": "Incorrect", "points": 0 }
        ]
      }
    ],
    "modelAnswer": "Napoleon rose to prominence as a general during the Revolution and later seized power, ending the revolutionary period while consolidating some of its reforms."
  },
  "tags": ["history", "french-revolution"],
  "externalId": "my_question_1",
  "metadata": { "my_service_internal_id": "abc1234" }
}

Fields

Field	Type	Description
`id`	string	The question's ID, assigned by Examplary.
`v`	number	Version number, incremented each time the question is edited.
`type`	string	ID of the question type, e.g. `single-line-text` or `examplary.expansion.matching`. Required.
`title`	string	The question stem shown to the student.
`description`	string	Optional supporting text shown below the title, such as context or instructions.
`settings`	object	Settings specific to the question type. Required (may be an empty object).
`scoring`	object	The rubric configuration set by the teacher. See Scoring below.
`tags`	string[]	Tags associated with the question, used for categorisation and search.
`externalId`	string	Optional ID you provide when creating the question via the API, used to correlate questions back to your own system.
`metadata`	object	An arbitrary key-value store for external system data (values may be strings, numbers, booleans, or `null`). Passed through unchanged.
`questionBankItemId`	string	The ID of the question bank item this question was added from, if any.
`traceIds`	string[]	Trace IDs used internally to track AI generation processes. You can ignore this field.

`type` and `settings`

The type field references a question type: one of the built-in question types or a custom question type published by your organisation.

The question type determines which settings are available. For built-in types these are listed on the default question types page; for custom types they are defined in the type's question-type.json metadata.

Scoring

The scoring object holds the rubric configuration used to grade the question:

Field	Type	Description
`rubricType`	string	The type of rubric: `simple`, `analytical`, `holistic`, or `exact-values`. See below.
`criteria`	array	The criteria for scoring the question. The expected shape depends on the rubric type.
`exactValuesCaseInsensitive`	boolean	Makes `exact-values` matching case-insensitive and strips surrounding whitespace before comparing.
`guidance`	string	Optional additional grading guidance text.
`modelAnswer`	string	Optional example model answer shown to graders.
`templateId`	string	The ID of the scoring template applied, if any.
`excludeFromGrading`	boolean	Excludes the question from the exam's total points and grade. See below. (pre-release)

Rubric types

The rubricType determines how the criteria array is interpreted:

simple — criteria have no levels, and their points stack: the total is the sum of the points for all criteria that apply.
analytical — at least one criterion, each with levels. For each criterion, a matching level is picked; the level's points count towards the total.
holistic — multiple criteria without levels. The grader selects a single criterion, and its points are the score.
exact-values — each criterion represents a specific value that must be matched exactly. Questions with this rubric type are graded automatically, as described in question grading.

Each entry in criteria (and each entry in a criterion's levels) has the following fields:

Field	Type	Description
`id`	string	A unique ID for the criterion or level. Required.
`title`	string	The title of the criterion or level. Only applies to analytical levels and holistic criteria.
`description`	string	Describes the requirements to earn the points for this criterion or level.
`points`	number	The default amount of points assigned when this criterion or level is selected.
`minPoints`	number	The minimum amount of points that can be assigned when this criterion or level is selected.
`maxPoints`	number	The maximum amount of points that can be assigned when this criterion or level is selected.
`levels`	array	The levels of an analytical rubric criterion, each representing a different point value for that criterion.

Excluding a question from grading (pre-release)

Setting excludeFromGrading: true in the scoring object leaves the question out of the exam's total points and grade. Excluded questions can still be answered and reviewed as normal — only the scoring calculation skips them, so response processing and AI-assisted grading still run and populate results as usual.

Where you encounter the Question object

REST API — questions are nested in the questions array when creating an exam, managed individually through the exam questions endpoints, and stored as reusable items in the question bank. See the REST API reference for the endpoints.
Custom question type components — the object is passed as the question prop to every component, so you can read settings, scoring, externalId and metadata when rendering. See question type components.
Embed sessions — flows such as generate question and mark answer produce or consume questions in this same shape.