---
title: "QTI 2.1 Package Rules: Manifest, Items and Answer Keys"
description: "What a QTI 2.1 .zip must contain to import cleanly: the manifest, one item per file, unique identifiers, answer keys and images, and how Formswrite writes it."
canonical: https://formswrite.com/formats/qti-2-1
last-updated: 2026-11-06
---

QTI 2.1 package rules

# What a QTI 2.1 package needs to import cleanly

Drop the .zip and see what an importer will read: how many items, which interactions, missing answer keys, broken image paths and repeated identifiers. Then fix it in Formswrite and export a clean package.

[Fix it in Formswrite](/accounts/signup?source=formats-qti-2-1)[Check a file](#check)

## The short version

QTI 2.1 is the IMS standard most test platforms mean when they say "QTI 2". A package is a .zip with an imsmanifest.xml that lists resources, one XML file per question (an assessmentItem), and usually an assessmentTest that strings the items together. Platforms such as TAO, itslearning and many publisher test engines import it.

Most failed imports come from a handful of causes: someone uploads the manifest instead of the .zip, two items share an identifier, an image path points at a file that is not in the package, or a choice item has no correctResponse so nothing can be scored.

Formswrite also writes QTI 2.1. Export a quiz and you get assessment\_test.xml, one file per item under items/, and a manifest that points at all of them with the imsqti\_item\_xmlv2p1 and imsqti\_test\_xmlv2p1 resource types. It is the package Formswrite sends for itslearning, Singapore SLS and TAO exports.

The checker on this page reads the package with the same reader Formswrite uses and lists each of those problems, question by question.

## Check your QTI 2.1 file

Drop a .zip or .xml file here, or choose one. It is read in memory to build the report and never stored.

Choose a file[Fix it in Formswrite](/accounts/signup?source=formats-qti-2-1)

items/Q001\_8F2A41C0.xml

```
<assessmentItem identifier="Q001_8F2A41C0" title="Capital of France"
    adaptive="false" timeDependent="false"
    xmlns="http://www.imsglobal.org/xsd/imsqti_v2p1">
  <responseDeclaration identifier="RESPONSE"
      cardinality="single" baseType="identifier">
    <correctResponse><value>b</value></correctResponse>
  </responseDeclaration>
  <outcomeDeclaration identifier="SCORE"
      cardinality="single" baseType="float"/>
  <itemBody>
    <choiceInteraction responseIdentifier="RESPONSE"
        maxChoices="1" shuffle="false">
      <prompt><div>What is the capital of France?</div></prompt>
      <simpleChoice identifier="a">Lyon</simpleChoice>
      <simpleChoice identifier="b">Paris</simpleChoice>
      <simpleChoice identifier="c">Nice</simpleChoice>
    </choiceInteraction>
  </itemBody>
  <responseProcessing template="http://www.imsglobal.org/question/qti_v2p1/rptemplates/match_correct"/>
</assessmentItem>
```

What the file contains

## What a QTI 2.1 package contains

Three kinds of file, all inside one .zip. The manifest names every resource, the test lists the items in order, and each item is a self contained question with its own answer key.

1.  ### imsmanifest.xml
    
    The package index. Each resource has a type (imsqti\_item\_xmlv2p1 for items) and an href to its file. Importers read items in the order listed here.
    
2.  ### assessment\_test.xml
    
    The test: one testPart, one section, and an assessmentItemRef per question pointing at items/<id>.xml.
    
3.  ### items/<id>.xml
    
    One assessmentItem per file. The responseDeclaration holds the key, the itemBody holds the prompt and the interaction.
    

## QTI 2.1 import rules

Each rule comes from the code that reads and writes QTI 2.1 files in Formswrite. "Will not import" loses the question or the file, "Changes on import" alters it, "How it is read" is good to know.

1.  Will not import
    
    ### Upload the whole package, not imsmanifest.xml or the assessmentTest file on its own.
    
    A lone manifest or test file only lists other files, so it is refused with "This is only the package description".
    
    Fix: Upload the .zip your platform exported, without unzipping it.
    
2.  Will not import
    
    ### The package holds at least one file whose root is questestinterop or assessmentItem.
    
    A .zip with neither is refused as having no QTI questions. A .zip that holds a Moodle XML file is read as Moodle XML instead.
    
    Fix: Check you exported the quiz or question bank, not the course files or a SCORM package.
    
3.  Will not import
    
    ### Each item file has one assessmentItem as its root element.
    
    An item file whose root is something else, or that nests several items inside another element, is not read as questions.
    
    Fix: Split the items into one file each under items/, the layout Formswrite itself exports.
    
4.  Changes on import
    
    ### Item identifiers are unique across the package.
    
    When two items share an identifier only the first is kept. This is how copies of the same item across files are removed, so two different items with one identifier lose the second.
    
    Fix: Give every item its own identifier attribute.
    
5.  How it is read
    
    ### imsmanifest.xml lists the item resources in quiz order.
    
    Questions are read in manifest order. Files the manifest does not list come after, sorted by name.
    
    Fix: Reorder the resource elements in the manifest, or reorder the questions after import.
    
6.  Changes on import
    
    ### Every image path an item points to resolves to a file inside the .zip, relative to that item file.
    
    A missing file is counted in the import warnings ("2 images were referenced but not found") and the question arrives without it.
    
    Fix: Add the image under the path the item uses, or fix the src attribute.
    
7.  Changes on import
    
    ### At most 200 embedded images per package are read.
    
    Images past the 200th are not attached to their questions.
    
    Fix: Split an image heavy bank into two packages.
    
8.  Changes on import
    
    ### An item has one interaction, unless all of them are inline blanks.
    
    An item with a choice and a text entry (for example) is read from its first interaction only, and the import warnings say so. Several inline text entry or inline choice blanks become one fill in the blank question.
    
    Fix: Split composite items into separate items.
    
9.  Changes on import
    
    ### Interactions are choice, text entry, extended text, upload, match, associate, order or inline choice.
    
    Hotspot, slider, gap match, hot text, drawing, select point, media, position object and the graphic interactions are skipped and listed by name.
    
    Fix: Rewrite those items as choice questions, or rebuild them in the target platform after import.
    
10.  Changes on import
     
     ### Choice items carry a correctResponse.
     
     Without one the question is read with no answer key. When Formswrite exports a choice item with no key, it marks the first choice correct so the item still scores.
     
     Fix: Set the right answer in the editor before you export, or add value elements to correctResponse.
     
11.  How it is read
     
     ### A choiceInteraction with maxChoices other than 1, or a multiple cardinality response, allows several answers.
     
     It is read as a multiple answers (checkbox) question with every correct value marked.
     
     Fix: Set maxChoices="1" and single cardinality if only one answer is right.
     
12.  How it is read
     
     ### A single answer item with exactly two choices, True and False, is a true or false question.
     
     It is read as true or false. Any other two options stay a normal multiple choice.
     
     Fix: Nothing to fix. Spell the choices True and False if you want the true or false type.
     
13.  How it is read
     
     ### A text entry item lists its accepted answers in correctResponse or in a mapping.
     
     Every value and every mapped key becomes an accepted answer. With none, the question imports with no key and is marked by hand.
     
     Fix: Add each spelling you accept as a mapEntry.
     
14.  Changes on import
     
     ### A match or associate item writes each correct pair as two identifiers, "A1 B2".
     
     Each pair becomes one matching row. A value that is not exactly two identifiers is dropped.
     
     Fix: Check directedPair values in the correctResponse.
     
15.  How it is read
     
     ### An order item gives the right order in correctResponse.
     
     The correct order is used when present, otherwise the order the choices appear in the file.
     
     Fix: Add the ordered value list if the file lists the choices shuffled.
     
16.  How it is read
     
     ### Formswrite exports use the standard match\_correct response processing template.
     
     An item scores full marks when the response matches exactly and zero otherwise. Partial credit on multiple answers is not written.
     
     Fix: Set partial credit in the target platform after import if you need it.
     
17.  Will not import
     
     ### The XML declares no entities and has no inline DTD.
     
     A file with an <!ENTITY> declaration or an internal DTD subset is refused for security. A plain DOCTYPE line pointing at a public DTD is fine.
     
     Fix: Export again from the platform. Hand edited files sometimes pick up a DTD block from a template.
     
18.  Will not import
     
     ### The XML is well formed.
     
     An unclosed tag, a stray ampersand or a broken CDATA block stops the whole file from being read.
     
     Fix: Open the file in a code editor that flags XML errors, or export it again instead of editing by hand.
     
19.  Will not import
     
     ### The file is 10 MB or smaller.
     
     A larger file is refused before a single question is read.
     
     Fix: Export the bank in two parts, or take large images out of the package and add them back in the platform.
     
20.  Will not import
     
     ### The .zip holds at most 2,000 files and unpacks to no more than 20 MB per file and 60 MB in total.
     
     A package over any of these limits is refused as too large.
     
     Fix: Export one quiz or one pool at a time rather than a whole course.
     
21.  Changes on import
     
     ### Paths inside the .zip are relative and never climb out with "..".
     
     Absolute paths, drive letters and ".." segments are ignored, and the report counts them as unsafe paths.
     
     Fix: Rebuild the package with every file under the package root.
     
22.  Changes on import
     
     ### Embedded images are PNG, JPEG, GIF, WebP or BMP and at most 5 MB each.
     
     Larger images and SVG files are not read, so the question arrives without its picture.
     
     Fix: Save diagrams as PNG and shrink photos before you build the package.
     
23.  Changes on import
     
     ### At most 1,000 questions per file.
     
     Only the first 1,000 usable questions are read, and the import warnings say how many the file had.
     
     Fix: Split a very large bank by unit or category and check each file on its own.
     

## Question types in QTI 2.1

Kept means it arrives as it was. Changed means a close equivalent. Fix first means an edit in the Formswrite editor before you export. Left out means the file has no place for it.

| Question type | From a QTI 2.1 file | In the Formswrite QTI 2.1 export |
| --- | --- | --- |
| Multiple choice | choiceInteraction with maxChoices 1 is read as multiple choice with the key. | KeptchoiceInteraction, maxChoices 1, with a correctResponse. |
| Multiple answers | maxChoices above 1 or multiple cardinality is read as checkboxes. | KeptchoiceInteraction with maxChoices set to the number of options and every right value. |
| True or false | Two choices named True and False become a true or false question. | ChangedA two choice choiceInteraction. |
| Short answer and fill in the blank | textEntryInteraction, with every value and mapped key accepted. | KepttextEntryInteraction with an expected length of 50 and your accepted answers. |
| Essay and paragraph | extendedTextInteraction and uploadInteraction become essay questions. | KeptextendedTextInteraction, 500 characters and 10 lines expected. |
| Matching | matchInteraction and associateInteraction pairs become matching rows. | Fix firstNot written as matchInteraction. It falls back to a text entry box. |
| Ordering (puzzle, jumble) | orderInteraction in the correct order. | Fix firstNot written as orderInteraction. It falls back to a text entry box. |
| Poll and survey questions | A choice item with no correctResponse comes in with no key. | Fix firstA choice item with the first choice marked correct. |

## CSV to QTI

A spreadsheet of questions does not import into a QTI platform as it is, because QTI needs one XML item per question and a manifest. Put the questions in a Google Sheet or an Excel file with the question, the options and the right answer in columns, convert the sheet in Formswrite, set the key in the editor, and export QTI 2.1.

Rows with no right answer are where most CSV conversions go wrong. A choice item exported without a key gets its first choice marked correct, so set the key before export rather than after.

## Word, PDF and plain text to QTI

A Word file, a PDF or a pasted list of numbered questions works the same way. Formswrite reads the questions and the options, you mark the right answers that the document did not state, and the export builds the items, the test and the manifest for you.

Short answer questions keep their accepted answers as a text entry interaction. Long answer questions become extended text items that a teacher marks by hand.

## How to import a QTI 2.1 file

1.  Pip
    
    ### Check the package here
    
    Drop the .zip in the checker. Fix anything listed under "Will not import" first, those questions are lost otherwise.
    
2.  Nova
    
    ### Fix it in Formswrite
    
    Open the quiz in the Formswrite editor, set missing keys, rewrite unsupported items as choice questions, and export QTI 2.1 again.
    
3.  Rio
    
    ### Import in your platform
    
    Upload the .zip in the platform’s QTI or content package import. Do not unzip it first.
    
4.  Kiki
    
    ### Spot check three items
    
    Open one choice item, one text entry item and one with an image, and confirm the key and the picture came through.
    

## Move a quiz in or out of QTI 2.1

-   ### QTI to Canvas
    
    Convert a QTI package to Canvas: upload the QTI package, fix the 2 question types Canvas cannot take, then download a Canvas QTI .zip.
    
    [Open the converter about QTI to Canvas](/convert/qti-to-canvas)
    
-   ### QTI to Moodle
    
    Convert a QTI package to Moodle: upload the QTI package, fix the 2 question types Moodle cannot take, then download Moodle XML. The answer key comes with it.
    
    [Open the converter about QTI to Moodle](/convert/qti-to-moodle)
    
-   ### QTI to Google Forms
    
    Convert a QTI package to Google Forms: upload the QTI package, fix the 2 question types Google Forms cannot take, then get a self grading Google Form.
    
    [Open the converter about QTI to Google Forms](/convert/qti-to-google-forms)
    
-   ### QTI to Kahoot
    
    Convert a QTI package to Kahoot: upload the QTI package, fix the 4 question types Kahoot cannot take, then download Kahoot's quiz spreadsheet.
    
    [Open the converter about QTI to Kahoot](/convert/qti-to-kahoot)
    
-   ### QTI to Word
    
    Convert a QTI package to Word: upload the QTI package, every question type fits, then download a printable Word test. The answer key comes with it.
    
    [Open the converter about QTI to Word](/convert/qti-to-word)
    
-   ### Moodle to QTI
    
    Convert a Moodle question bank to QTI: upload the Moodle XML, fix the one question type QTI cannot take, then download a QTI 2.1, 2.2 or 1.2 package.
    
    [Open the converter about Moodle to QTI](/convert/moodle-to-qti)
    

## Questions people ask

What is the difference between QTI 2.1 and 2.2?

The question model is almost the same. 2.2 changes the namespaces, the resource types in the manifest and the metadata profile. Use the version your platform asks for. Formswrite exports both.

Why did a question disappear on import?

The usual reasons are an unsupported interaction such as a hotspot, an item that shares its identifier with another item, or a file whose root is not assessmentItem. The rules below cover each of these.

Can Formswrite export QTI 2.1 from a Word document?

Yes. Add the document in Formswrite, review the questions and the answer key in the editor, and choose QTI 2.1 as the export. Exports other than Formswrite Forms need a paid plan.

Does the checker validate against the QTI XSD?

No. It checks structure and content the way an importer reads it: the manifest, item roots, identifiers, answer keys, interactions and image paths. A package can pass the XSD and still lose questions on import, which is what the checker is for.

Is my file stored?

No. The checker reads the file in memory, builds the report and keeps nothing.

## Keep reading

-   [Documents to QTITurn a Word file, PDF or Google Doc into a QTI 2.1 or 2.2 package.](/product/documents-to-qti)
-   [QTI format explainedWhat QTI is, the versions, and which platforms import each one.](/blog/qti-format-explained)
-   [CSV to QTI guideHow spreadsheet questions become a QTI package, column by column.](/blog/csv-to-qti-converter-guide)
-   [Move a quiz between platformsPick where the quiz lives now and where it needs to go.](/convert/platforms)

## Make a clean QTI 2.1 file from your document

Upload a Word file, PDF or Google Doc, check the questions and the key in the editor, then export. Exports other than Formswrite Forms need a paid plan.

[Fix it in Formswrite](/accounts/signup?source=formats-qti-2-1)[How the export works](/product/documents-to-qti)
