Question type definition

A question type is defined in TypeScript as a new QuestionType() from @examplary/apps, usually in a definition.ts in the question type's own folder. Here's an example as a starting point:

import { QuestionType } from "@examplary/apps";
 
export default new QuestionType({
  id: "com.acme.quiz.short-answer",
  name: {
    en: "Short answer",
    nl: "Kort antwoord",
  },
  description: {
    en: "A question that requires a short text response.",
    nl: "Een vraag die een kort tekstantwoord vereist.",
  },
  icon: "./short-answer/icon.svg",
  components: {
    assessment: "./short-answer/component-assessment.tsx",
    print: "./short-answer/component-print.tsx",
  },
  readme: { en: "./short-answer/README.md", nl: "./short-answer/README.nl.md" },
  previewImage: "./short-answer/preview.png",
  timeEstimateMinutes: 2,
  generation: {
    enabled: true,
  },
  translations: {
    placeholder: {
      en: "Type your answer...",
      nl: "Typ je antwoord...",
    },
  },
});

Your app then adds it in app.ts:

import ShortAnswer from "./short-answer/definition";
 
app.addCapability(ShortAnswer);

Question type ID

The id field uniquely identifies your question type across Examplary. It must follow this format:

• Starts with your app's ID: the app com.acme.quiz can add com.acme.quiz.short-answer
• Dot-separated namespacing: must contain at least one dot (e.g. com.acme.quiz.multiple-choice)
• Lowercase only: each segment may only contain lowercase letters (a–z), digits (0–9), or hyphens (-)
• Letter-first: each segment must start with a letter, not a digit or hyphen

As app IDs use reverse domain notation, so do the IDs of their question types, which keeps them from clashing with other question types.

Translatables

Most of the fields that are displayed in the UI can be translated. The name and description fields are good examples of this. You are encouraged to provide translations for all supported languages.

If you don't want to translate the field yet, you can also use a simple string field:

new QuestionType({
  name: "Short answer",
});

Name, description and icon

The name and description fields are used to display the question type in the UI. The icon field points to the SVG icon that represents the question type.

This SVG will be displayed in the question adder, and possibly in other places in the UI. Specifications:

• Displayed as a 24×24‑pixel icon
• Should either use black or currentColor as the only fill color

Most of the icons in the default question types are based on Lucide icons. You can use these icons as a starting point for your own question type icons. We recommend a stroke width of 2.25px when exporting the SVG from the Lucide website.

Components

The components field is an object that defines the React components used for different views of the question type. The keys are the view names, and the values are the paths to the component files.

Component files can be written in TypeScript or JavaScript, and should have a default export that is a React component. The component will receive the question data as props, which you can use to render the question in the specific view.

new QuestionType({
  components: {
    assessment: "./short-answer/component-assessment.tsx",
    print: "./short-answer/component-print.tsx",
  },
});

More information about the components can be found in the components documentation.

Questions without any components are allowed, but are only useful in specific cases (the default question types include 'paragraph', 'intro' and 'outro' which do not have any components). If you don't provide any components, the student can't interact with the question in the assessment view, but the title and description will still be displayed.

Settings

Question types can have settings that are displayed in the question editor:

These settings are defined in the settings of the definition. Default fields 'question type', 'tags', and 'scoring criteria'/'points' will always be present, but in this example the following were added:

new QuestionType({
  settings: [
    {
      id: "minWords",
      name: {
        en: "Minimum word count",
        nl: "Minimaal aantal woorden",
      },
      type: "number",
      placeholder: "0",
      step: 50,
    },
    {
      id: "maxWords",
      name: {
        en: "Maximum word count",
        nl: "Maximaal aantal woorden",
      },
      type: "number",
      placeholder: "0",
      step: 50,
    },
  ],
});

You can also add settings one at a time with addSetting(), after those in the definition:

const essay = new QuestionType({
  // ...
});
 
essay.addSetting({
  id: "minWords",
  name: { en: "Minimum word count", nl: "Minimaal aantal woorden" },
  type: "number",
  placeholder: "0",
  step: 50,
});
 
export default essay;

Each settings object can have the following fields:

The following settings types are supported:

• enum - A dropdown with a list of options. The options field is required.
• boolean - A checkbox/switch. The value will be true or false.
• number - A number input field. The placeholder, step, min and max fields are optional.
• string - A single-line text input field. The placeholder field is optional.
• string-array - A multi-value input where users can add and remove string entries. Stored as an array of strings.
• custom - A value of any shape, such as an object or a list of objects, that has no input in the question editor. Your own components can read and write it. Describe its shape in schema so AI-generated questions fill it in correctly.

Optional fields

These other fields are available in the definition: