QTI 3 migration: plan and test an item-bank move

Define the migration scope

Write down what is moving, where it is going, and which behavior must survive. “Move the question bank” is too vague for acceptance.

Record the following details:

• Source platform and export mechanism
• QTI version or proprietary format
• Number of banks, items, tests, pools, and shared stimuli
• Interaction and question types
• Scoring patterns and partial-credit rules
• Assets, stylesheets, math, media, and external links
• Accessibility metadata and support materials
• Local taxonomies, ownership, lifecycle, and analytics identifiers
• Destination authoring and delivery systems

Keep the original packages unchanged. Migration output should be reproducible from a named source artifact and converter version.

Reasons to migrate

Migrate when a required destination cannot use the source format reliably, your institution needs an exit archive, an authoring workflow changes, or legacy content blocks accessibility and maintenance work.

Do not convert content solely to claim a newer version. If your current authoring and delivery systems exchange the required QTI 2.x profile without loss, you may keep that path while you pilot QTI 3. The QTI 2 versus QTI 3 comparison provides the decision criteria.

Set a measurable result. For example, require a QTI 3 archive that imports into two named systems, preserves required metadata and scoring, and passes your institution’s accessibility review.

Account for version differences

QTI 1.2, QTI 2.x, the Accessible Portable Item Protocol (APIP), and QTI 3 do not share a single element-for-element model. QTI 3 consolidates QTI and APIP work, uses current web-oriented element naming, and expands shared presentation vocabulary and accessibility-related structures.

Profile differences matter as much as version differences. A source may use only a basic subset, or it may depend on custom processing, local metadata, proprietary classes, and extensions. Inventory the corpus before choosing a mapping strategy.

Define acceptable changes

Some source content does not map cleanly to QTI 3. Your institution must decide which changes are acceptable and which require repair or rejection.

Record those decisions before bulk conversion. For example, you might allow a local display label to move into a documented extension while rejecting any change to correct responses, scoring, reading order, accessible names, or media alternatives.

Classify each field or behavior by using one of the following actions:

• Preserve exactly
• Map to a QTI 3 equivalent
• Preserve as a documented extension
• Transform with review
• Omit with an explicit warning
• Block migration

Do not let the converter make policy silently.

Profile the source content

Sample files often contain only the easiest items. Analyze the full corpus before estimating effort.

Group content by structural signature: interaction type, response declaration, processing rule, asset pattern, namespace, extension, and source version. Count each group. Pull representative items from common groups and every rare or high-risk group.

Inspect malformed content separately. Old systems may import files they would never export cleanly. Decide whether the migration tool repairs known source defects, preserves them for another step, or stops.

Build an explicit mapping

Map source constructs to QTI 3 semantics before mapping element names. QTI 1.2, QTI 2.x, APIP, and vendor formats can express similar ideas through different structures.

For every mapping, document the following details:

• Source signature
• QTI 3 target
• Identifier policy
• Response and outcome types
• Scoring transformation
• Content and asset handling
• Accessibility handling
• Diagnostics
• Automated fixtures
• Review requirement

Version the mapping rules. A migration completed with rule set 1.4 should remain explainable after rule set 1.5 ships.

Preserve identity and provenance

When source item identifiers are valid and unique, preserve them. If an identifier must change, generate a new one and record the relationship in a crosswalk.

The crosswalk should include source system, source bank, source identifier, destination identifier, source checksum, converter version, migration date, and disposition. Keep it outside candidate-facing content.

Do not put personal data into generated identifiers or diagnostic messages.

Move assets as package content

Download source-managed assets while access still exists. Normalize unsafe or ambiguous paths, but keep a record of each rewrite. Package-relative references are easier to transfer than authenticated source URLs.

Check the following asset properties:

• Missing files and broken references
• Duplicate names with different content
• Filename case differences
• Path traversal
• Unsupported or mislabeled media types
• Images that contain essential text
• Caption and transcript relationships
• Cascading Style Sheets (CSS) that assume a source application shell

Generate a manifest of original and migrated asset checksums. This catches silent corruption and supports later audits.

Remediate accessibility during migration

Conversion can preserve known alternatives and support materials, but it cannot invent the author’s intent. Flag images without useful alternatives, sensory-only instructions, uncaptioned media, unclear link text, visual reading order, inaccessible tables, and interactions without a keyboard path.

Route those items to an accessibility and content review. Record whether the reviewer preserved, repaired, replaced, or retired the item. Then test the repaired item in the destination player with the assistive-technology combinations in your institutional support policy.

If candidates lose an accessible way to answer an item, do not label its migration successful.

Convert response processing carefully

Visual similarity can hide scoring changes. Compare declarations, correct responses, mapping tables, thresholds, template references, outcome values, and custom conditions.

Create test vectors for each of the following response states:

• Unanswered
• Correct
• Incorrect
• Partially correct
• Extra choices
• Minimum and maximum responses
• Invalid input
• Restored attempt state where relevant

When possible, run the source system and record expected outcomes. Then run the migrated item through the target processor. Differences belong in the exception register.

Check preserved and rejected examples

Longsight reviewed the qti3 migrator in version 0.13.1 on October 5, 2026. Its synthetic tests show specific conversions that preserve meaning and specific conversions it refuses. Use these examples to define your pilot’s acceptance criteria, then test your institution’s content in the destination system.

The following examples preserve the stated behavior:

Source behavior	Expected migrated result	Public test evidence
QTI 2.0 choice with the standard match-correct template	Correct answer earns 1 point. Incorrect and unanswered responses earn 0.	Choice-grade preservation tests
QTI 2 item language and instructions before and after a choice interaction	The language and content order remain intact. Correct, incorrect, and unanswered scores remain unchanged.	Item-preservation tests
Extended text restricted to three uppercase letters	ABC meets the migrated pattern. abc and ABCD do not.	Text-constraint tests
Hotspot instructions, region labels, and an image description	The migrated item retains the instructions, labels, description, and tested scores.	Hotspot-preservation tests
QTI 1.2 ordered text and images	The content stays in order. Text marked as plain text remains literal rather than becoming HTML.	Material-preservation tests

The same version refuses the following cases rather than reporting a successful conversion:

Source behavior the conversion cannot preserve	Expected result	Public test evidence
QTI 2 modal feedback	An error diagnostic and no successful migrated XML	Feedback-refusal tests
A matching group that excludes otherwise available choices	An error diagnostic rather than an item with unrestricted matching	Matching-restriction tests
A QTI 1.2 item that awards credit only when two separate answers are both correct	An error diagnostic rather than an item that grades only the first answer	Composite-response tests
A response declaration the writer would omit	An error diagnostic rather than output with a missing response	Response-preservation tests

Safe repair does not override the tested feedback, matching-group, or two-answer refusals. Keep the original item and route its diagnostic to the migration owner. A rejected item is an exception to resolve, not a successful conversion with fewer features.

Item conversion also differs from test migration. The reviewed migrator returns items in a flat review part and reports the loss of assessment-test structure. Rebuild and test the required sequencing in the destination rather than assuming it survived the item conversion. The QTI implementation matrix separates migration behavior from the library’s test-execution profile.

These tests use synthetic content and the qti3 processor. They do not establish that an independent LMS imports, renders, or scores the output correctly. The downloadable test report records the local review scope.

Record unsupported content

Custom interactions, scripts, vendor extensions, complex adaptive behavior, and test-level navigation may not have a safe automatic mapping.

Use one of the following dispositions:

• Converted automatically
• Converted with warning
• Converted for author review
• Retained in source form
• Not converted

If the converter replaces an unsupported interaction with a screenshot or unscored text, do not label the item successful without an explicit institutional decision.

Validate in stages

Use gates so failures remain diagnosable:

1. Parse and inventory the source.
2. Convert one item to QTI 3.
3. Check XML and schema validity.
4. Run semantic and supported-profile checks.
5. Compare declarations and scoring fixtures.
6. Render and operate the item with keyboard and assistive technology.
7. Package the item and its assets.
8. Import the package into the destination.
9. Deliver and score it in the destination workflow.
10. Reconcile counts, identifiers, assets, outcomes, and exceptions.

Schema validation belongs near the start. Destination testing belongs near the end. Neither replaces the other.

Run a representative pilot

Choose a pilot by risk and frequency, not convenience. It should include common items, rare interactions, partial credit, math, media, accessibility support, large packages, and known source defects.

Have content owners review meaning and scoring. Have accessibility specialists review candidate operation. Have platform teams test import, editing, delivery, export, and restoration. Record the destination build and configuration.

Begin bulk conversion after the team approves the mapping rules and the process for handling exceptions.

Reconcile the bulk run

Reconcile the following counts at each step:

• Packages read
• Items discovered
• Items converted
• Items blocked
• Assets found and missing
• Warnings by code
• Destination imports
• Destination items

Totals should reconcile with named exceptions. A dashboard that says “99.4% successful” is not enough when the missing 0.6% contains high-stakes exams.

Keep an exception register

Each exception needs the source item, diagnostic code, plain-language explanation, severity, owner, chosen action, and final disposition. Group repeat failures so one mapping fix can be rerun across affected items.

Do not leave warnings only in temporary logs. Export a report that content teams can filter and annotate.

Plan the cutover and exit

Define when the source becomes read-only, who handles last-minute changes, which system owns identifiers after cutover, and how rollback works.

After acceptance, export a clean QTI 3 archive from the destination and validate it independently. Keep that export as part of the migration record and test the exit process before closing the project.