Getting started

This guide starts with a YAML question bank and ends with the QTI ZIP file that Canvas receives. You do not need to understand Python code, XML, or the QTI file format.

1. Install Python

QuestionBankToolkit requires Python 3.14 or newer. Download a current Python release from python.org or use a trusted package manager supplied by your operating system.

Open Terminal on macOS or Linux, or PowerShell on Windows, and check the installed version.

python --version

If that command does not find the intended interpreter on macOS or Linux, try python3.14 --version. On Windows, the Python install manager also provides py -3.14 --version.

2. Install QuestionBankToolkit

Create an isolated virtual environment so the toolkit and its dependencies do not change other Python applications.

On macOS or Linux, run:

python3.14 -m venv .venv
source .venv/bin/activate
python -m pip install QuestionBankToolkit

On Windows PowerShell, run:

py -3.14 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install QuestionBankToolkit

The terminal prompt usually displays (.venv) while the environment is active. Verify the command installation before writing a bank.

coursebanks --help

Return to the directory containing the environment and activate it before later sessions. Installing from a Git checkout and installing development tools are optional contributor workflows described in development.md.

3. Create a YAML bank

Copy the complete bank below into a UTF-8 text file named questions.yaml. It is also available as the checked-in sample.

schema_version: 1
course: COURSE123
bank_id: Module1_Conceptual
title: COURSE123 Module 1 Conceptual Questions
default_shuffle_choices: true
questions:
  - id: M1C01
    title: Interpreting a reference scale
    area: Mathematical foundations
    topic: Nondimensional variables
    difficulty: Basic
    assessments: []
    minutes: 2
    points: 2
    format: plain
    stem: If a dimensional quantity is divided by its own reference scale, what is the result?
    choices:
      A: A dimensionless quantity.
      B: A dimensional quantity with squared units.
      C: An identically zero quantity.
      D: A quantity that cannot be compared between experiments.
    answer: A
    explanation: The units cancel when a quantity is divided by a reference scale with the same units.

YAML uses spaces and indentation to show structure. Keep every question two spaces beneath questions:, its fields four spaces beneath the dash, and each choice six spaces beneath choices:. Do not use tab characters.

The top-level course, bank_id, and title identify the bank and its generated files. Each id must be unique and stable because QTI, reports, imports, and usage history use it to identify the question. The area, topic, difficulty, and minutes fields help instructors review and select questions; Canvas grading uses points. An empty assessments: [] list allows the question to be used for any assessment. Use a list such as assessments: ["Quiz 1", "Final"] to restrict optional selection workflows.

The keys below choices: are answer labels. The answer value must exactly match one choice key, including capitalization. The explanation becomes general feedback in the generated QTI package.

Quote text when YAML punctuation could change its meaning. For example, write title: "Week 1: Forces", topic: "#hashtags", and assessments: ["1"]. Do not quote points, minutes, true, or false, because those fields require YAML numbers or booleans rather than text.

Use YAML’s folded block style for a long paragraph.

stem: >-
  A long question can continue on additional indented lines.
  YAML folds these lines into one paragraph.

Use the literal block style when line breaks must remain part of authored HTML or text.

explanation: |-
  First line of feedback.
  Second line of feedback.

See the YAML schema for every field, valid value, default, and identifier rule.

4. Validate before building

Run validation from the directory containing questions.yaml.

coursebanks validate questions.yaml

A valid copy of the sample prints:

Valid: COURSE123 / Module1_Conceptual: 1 questions

An invalid bank returns status 2 and prints an ERROR: diagnostic. Read the first field named by the message, correct the YAML, save the file, and rerun validation until it succeeds.

Common corrections include:

  • Align a field with the other fields in the same question when YAML reports a parsing or indentation error.

  • Change a duplicate id or repeated question stem so each question is distinct.

  • Make answer match one key under choices exactly.

  • Use Basic, Moderate, or Challenging with the documented capitalization.

  • Remove quotation marks around numeric minutes and points values.

  • Add missing required fields and ensure text is not blank.

The command troubleshooting guide covers missing files, paths with spaces, and other diagnostics.

5. Build the Canvas package

Build all deliverables into a directory named build.

coursebanks build questions.yaml --out build

The sample prints a summary containing the archive path, question count, and SHA-256 digest. The digest is a fingerprint that lets you identify the exact ZIP that was reviewed.

Created build/COURSE123_Module1_Conceptual_QTI12.zip: 1 questions; SHA-256 ...

The build directory contains four files.

File

Purpose

COURSE123_Module1_Conceptual_QTI12.zip

Upload this unopened ZIP file to Canvas.

instructor_review.md

Readable review of stems, choices, answer keys, explanations, and authoring metadata.

question_catalog.csv

Spreadsheet-friendly catalog for filtering questions by area, topic, difficulty, eligibility, time, and points.

validation.json

Machine-readable build record containing item IDs, counts, difficulty totals, and the ZIP digest.

Open instructor_review.md and confirm the wording, answer, feedback, points, and intended choice shuffling before upload. Do not give this instructor-only file to students because it contains answer keys. Use question_catalog.csv for review and inventory; it is not the Canvas upload file.

Run the structural QTI check if the ZIP has been moved, renamed, or copied.

coursebanks check-qti build/COURSE123_Module1_Conceptual_QTI12.zip

A successful check prints Valid QTI 1.2 structure: 1 questions. This local check verifies the toolkit’s supported package structure but cannot predict every institutional Canvas setting or rendering difference.

6. Import and review in Canvas

Follow Importing the generated package into Canvas for separate Classic Quizzes, New Quizzes, and New Quizzes item-bank procedures. Upload COURSE123_Module1_Conceptual_QTI12.zip, then preview every imported question before publishing or assigning it.

Optional workflows

Importing an existing QTI archive back into YAML is covered in Importing QTI into YAML. Question selection, usage recording, and multi-term rotation planning are optional instructor workflows listed in the command reference. Git, editable installation, testing, linting, typing, and source contributions are covered in the developer guide.