QTI 3 authoring: a practical guide to portable assessment items

Define the response first

A QTI item connects a prompt to a response declaration, one or more interactions, response processing, outcomes, accessibility information, and referenced assets. Those parts must agree.

Start by naming what the item records. A single-choice item usually returns one identifier. A multiple-choice item returns several identifiers. A text-entry item may return a string, while a slider commonly returns a number. Cardinality and base type are not implementation details. They define what a delivery system can accept and what the scoring rules can process.

Write the response declaration before designing the editor control. Otherwise, the interface may collect a different response type than the exported item declares.

The fragment below shows the identifier shared by a declaration and its interaction:

<qti-response-declaration
  identifier="RESPONSE"
  cardinality="single"
  base-type="identifier">
  <qti-correct-response>
    <qti-value>answer-b</qti-value>
  </qti-correct-response>
</qti-response-declaration>

<qti-choice-interaction response-identifier="RESPONSE" max-choices="1">
    <qti-prompt>Which standard exchanges assessment items?</qti-prompt>
  <qti-simple-choice identifier="answer-a">LTI</qti-simple-choice>
  <qti-simple-choice identifier="answer-b">QTI</qti-simple-choice>
</qti-choice-interaction>

The public qti3 repository contains complete fixtures and expected outcomes. Use full items and packages for validation and interoperability tests.

Know what the standard defines

QTI defines data models for assessment items, tests, results, metadata, packaging, response processing, accessibility information, and candidate preferences. It defines how systems exchange that data. Institutions and products must still provide authoring workflows, review policies, identity services, item-bank permissions, proctoring, and accommodation processes.

An authoring system must prevent inconsistent declarations, preserve imported information it does not edit, manage assets, show useful diagnostics, keep revision history, and produce packages another system can inspect. Writing XML is only one part of authoring.

Build an item from stable identifiers

Identifiers connect the item body to declarations and processing rules. They also help institutions compare revisions, reconcile item banks, and interpret diagnostics.

Use identifiers with all of the following characteristics:

• Unique within the required scope
• Stable across ordinary edits
• Free of student, course, or other sensitive data
• Generated by a documented rule
• Preserved during import and export unless a collision requires a change

Do not regenerate every identifier during each export. That makes a harmless text edit look like a new item and weakens audit history.

Choose the interaction from the response

Select the QTI interaction that matches the response model and the candidate action. Do not replace a standard interaction with arbitrary HTML or a custom widget for one renderer. Other systems may not be able to import, edit, or deliver it.

For each supported interaction, document the following details:

• The QTI element and required child elements
• Allowed cardinality and base type combinations
• Constraints such as minimum and maximum choices
• Keyboard and pointer behavior
• Accessible name and instruction strategy
• Scoring behavior
• Asset and styling requirements
• Tested importers and players

Portable Custom Interaction can be appropriate when the standard interactions cannot express the task. It introduces a host contract and therefore needs stronger packaging, security, accessibility, and fallback review.

Author semantic content

Use QTI and HTML semantics before styling hooks. Headings should form a logical outline. Lists should be lists. Tables need headers that identify their rows and columns. Images need alternatives that serve the item without disclosing the answer.

Do not place essential instructions only in placeholder text, color, layout, or an image. Candidate-facing help and validation messages need a programmatic relationship to the interaction they describe.

QTI 3 includes a shared Cascading Style Sheets (CSS) vocabulary. Use those classes for their defined meaning, and preserve them during import. A receiving system may render the item differently, but it can still recognize the author’s intent.

Treat accessibility as authored data and delivered behavior

QTI 3 brings forward accessibility work from the Accessible Portable Item Protocol (APIP) and includes structures related to Personal Needs and Preferences (PNP). That foundation helps systems exchange information, but it does not make every item or player accessible.

The authoring system should help an author complete the following tasks:

• Provide text alternatives and long descriptions where needed.
• Avoid sensory-only instructions.
• Describe time-based media and provide captions or transcripts.
• Check that interaction instructions remain clear without visual layout.
• Preview keyboard order and visible focus.
• Identify content that may conflict with a candidate preference.
• Record support material without embedding private candidate data in the item.

The delivery system must still apply preferences, render controls, manage focus, announce errors, and maintain contrast. Test the authoring output and candidate delivery separately.

Keep metadata useful

Record metadata that another system or institutional process uses. This may include language, subject or taxonomy references, educational level, ownership, license, lifecycle status, and revision information.

Avoid local fields with undocumented meanings. If a local extension is necessary, define its namespace, allowed values, preservation rules, and what happens when a receiving system does not understand it.

Do not store secrets, candidate records, or operational access rules in a portable item package.

Make response processing reviewable

Response processing determines outcomes from candidate responses. Template rules can cover many common scoring patterns and are easier for different systems to recognize. Custom response processing can express more, but it requires stronger testing.

Review the rules with concrete examples:

1. The empty or unanswered response
2. Each correct response
3. Plausible incorrect responses
4. Partially correct combinations
5. Responses at declared minimum and maximum limits
6. Restored responses from a saved attempt

Record expected outcomes as fixtures. A visual preview is not enough; the same response should produce the expected score in automated tests.

Preserve assets and styles

Images, audio, video, stylesheets, and companion materials must travel with the item or resolve through an explicit package relationship. Relative references should remain valid after the package moves.

Validate paths before extraction. Reject traversal outside the package root, unsafe URL schemes, unexpected file types, and ambiguous duplicates. When a system generates previews or transformed copies, keep the original assets immutable.

Item styles must not override candidate controls, conceal content, or break the host page. A delivery system needs a deliberate policy for package CSS rather than silently attaching every stylesheet.

Import earlier QTI versions

Institutions rarely begin with a clean QTI 3 bank. An authoring system may need to read QTI 1.2, QTI 2.x, APIP, and vendor extensions. Each source construct needs an explicit QTI 3 mapping, a diagnostic, and a preservation rule.

Keep the original package and source identifier. Record the converter version and any identifier rewrite. Send unsupported interactions, custom processing, missing assets, and ambiguous accessibility information to a review queue instead of flattening them silently.

After import, compare response declarations, correct responses, processing rules, metadata, assets, and candidate behavior. Displaying the prompt alone does not show that the item survived the import. The QTI 3 migration guide provides the full acceptance workflow.

Separate authoring from delivery

The authoring system manages item construction, revision, review, validation, and export. The delivery system manages candidate sessions, identity, authorization, time and attempt rules, preferences, navigation, responses, scoring, and attempt records.

A preview helps an author check rendering and scoring. It does not test your institution’s delivery shell, learning management system (LMS) launch, accommodation rules, or grade-return path. Test those integrations separately.

Keep delivery secrets and candidate records out of portable items. The host can combine a QTI item with private session data at delivery time.

Build revision and review into the workflow

Store each substantive item revision with its author, date, source, validation result, and review state. Preserve stable identifiers across ordinary edits and give released revisions immutable references.

A practical workflow uses the following states:

• Draft content that may change
• Technical validation
• Content or subject review
• Accessibility review
• Approval for use
• Retirement or replacement

Define who can move an item between states and what evidence each transition requires. When an imported item changes during remediation, keep the original, the corrected revision, and the reason for the change.

Use AI drafts as untrusted input

An AI system can propose a prompt, distractors, feedback, or metadata. The authoring system still has to create the QTI structure and a person still has to review accuracy, bias, accessibility, scoring, copyright, and fit for purpose.

Do not let generated prose bypass declarations and validation. Convert the draft into the same typed item model used for human-authored content. Require stable identifiers, explicit correct responses, reviewable processing rules, alternatives for media, and normal approval states.

When institutional policy requires it, record that a draft used an automated source. Do not put private prompts, model credentials, student records, or hidden evaluation data into the portable item.

Validate in layers

Run separate checks because each one answers a different question:

1. XML: Is the document well formed?
2. Schema: Does it match the required QTI XML binding?
3. Semantics: Do declarations, references, types, and processing rules agree?
4. Profile: Does it stay inside the supported subset of the target systems?
5. Accessibility: Can candidates perceive, operate, and understand the item?
6. Rendering and scoring: Does the item behave as expected in a real player?
7. Interoperability: Does an independent system import and deliver it without material loss?

The QTI validation guide explains how to keep these results separate.

Package for transfer

An export should include the item XML, required assets, declared relationships, and package metadata. Use stable paths. Generate entries in a consistent order so equivalent exports do not create noisy diffs.

Before release, unpack the export into a clean environment. Validate it from the package rather than from the authoring database. Then import it into at least one independent implementation that matters to your institution.

Common authoring failures

• The interaction response identifier has no matching declaration.
• Cardinality or base type conflicts with the interaction.
• Correct values and response processing disagree.
• Choice identifiers change on every save.
• Imported assets work only through the source system’s URLs.
• Styling carries meaning that the item structure does not.
• A preview works with a mouse but not with a keyboard.
• The export drops local metadata or silently changes a question type.
• “QTI compatible” means only one successful import from one source.

Each failure should produce a diagnostic that names the item, location, rule, and a practical next action without exposing candidate data.

Set acceptance criteria

Define what your institution needs for its content, candidates, systems, and exit plan.

Define the required interaction set, accessibility tests, import sources, export destinations, scoring cases, and acceptable loss before implementation starts. Keep representative items in a shared acceptance suite. When the authoring tool, player, schema set, or destination platform changes, run that suite.

Record the tested content, its behavior, and the items that still need review. A general compatibility statement does not provide that detail.

During evaluation, ask suppliers to demonstrate import, editing, revision history, accessibility repair, validation, packaging, and export with your institution’s representative content. Request diagnostics and the resulting QTI package. Then test that package outside the authoring product.