Moodle XML format explained, with a downloadable example

Moodle XML is the file format Moodle uses to export questions from a question bank and to import them into another course or site. It carries every core question type, with pictures and formulas inside the file, which is why tools that turn tests into Moodle questions write it. You rarely need to write it by hand, but knowing what is inside helps when an import goes wrong or a question behaves differently than you expected.

This page walks through a real file, part by part. Both files of the example can be downloaded: a short Word test, and the Moodle XML that the free ExamQR quiz converter made from it.

The outline of a file

A Moodle XML file is a <quiz> element holding a list of <question> elements. The type attribute says what each one is. The example contains these:

Moodle also knows matching, description (text with no answer, such as a reading passage), gapselect, ddwtos and others. Questions of types added by plugins import only on sites that have those plugins.

Categories

<question type="category">
  <category>
    <text>$course$/top/moodle-xml-example/Part 1. Multiple choice</text>
  </category>
</question>

Every question after this entry goes into the category Part 1. Multiple choice, inside a category named after the file, at the top of the course's question bank ($course$). On Moodle's import page, Get category from file decides whether these entries are used. Untick it to put all questions into the category you choose instead.

What every question has

<question type="multichoice">
  <name><text><![CDATA[Q1: Which device keeps data when the computer is switched off?]]></text></name>
  <questiontext format="html">
    <text><![CDATA[<p>Which device keeps data when the computer is switched off?</p>]]></text>
  </questiontext>
  <generalfeedback format="html"><text></text></generalfeedback>
  <defaultgrade>1.0000000</defaultgrade>
  <penalty>0.0000000</penalty>
  <hidden>0</hidden>
  …

• name is what you see in the question bank list, not what students see. The converter starts it with the question number, so the bank keeps your order.
• questiontext is the question as HTML. CDATA lets the HTML sit inside the XML without escaping every <.
• generalfeedback is shown to students after they answer, when the quiz review options allow it. A worked solution written in the Word file under "Solution:" goes here.
• defaultgrade is the question's marks; penalty is what each wrong try costs in quizzes that allow several tries.

Multiple choice

  <single>true</single>
  <shuffleanswers>true</shuffleanswers>
  <answernumbering>ABCD</answernumbering>
  <answer fraction="0"><text><![CDATA[RAM]]></text></answer>
  <answer fraction="100"><text><![CDATA[Hard disk]]></text></answer>
  <answer fraction="0"><text><![CDATA[CPU cache]]></text></answer>
  <answer fraction="0"><text><![CDATA[Graphics card]]></text></answer>

• fraction is the share of the marks an answer earns, in percent: 100 for the correct one, 0 for the others.
• single is true for one correct answer (radio buttons) and false when several are correct (tick boxes). In question 5 of the example, Python and Java each have fraction="50" and the two wrong options fraction="-100", so a wrong tick cancels the marks; Moodle never goes below zero for a question.
• shuffleanswers lets Moodle reorder the options for each student, if the quiz also allows it. Question 2 ends with "All of the above", which must stay last, and Moodle cannot pin one option, so the converter writes false for that question and tells you so.

True or false

Moodle's truefalse question holds one statement. A Word question with four statements a) to d) therefore becomes four Moodle questions, each worth a quarter of the marks (defaultgrade 0.25), with the shared instruction repeated above each statement:

<question type="truefalse">
  <questiontext format="html"><text><![CDATA[<p>Decide whether each statement about networks is true or false.</p>
    <p><b>b)</b> The internet is a single network owned by one company.</p>]]></text></questiontext>
  <defaultgrade>0.2500000</defaultgrade>
  <answer fraction="0"><text>true</text></answer>
  <answer fraction="100"><text>false</text></answer>

Short answer and numbers

<question type="numerical">
  …
  <answer fraction="100"><text>11</text><tolerance>0</tolerance></answer>

<question type="shortanswer">
  …
  <usecase>0</usecase>
  <answer fraction="100"><text>Ctrl+C</text></answer>

• An answer that is a number becomes numerical, so "11", "11.0" and " 11" are all accepted. tolerance allows a margin, for example 0.5 for measured values.
• Other answers become shortanswer. usecase 0 ignores capital letters. Several accepted answers are several <answer> elements, each with fraction 100.

Essay

<question type="essay">
  …
  <responseformat>editor</responseformat>
  <responserequired>1</responserequired>
  <responsefieldlines>15</responsefieldlines>
  <attachments>0</attachments>
  <graderinfo format="html"><text></text></graderinfo>

Essays are marked by a teacher, so there is no correct answer. responseformat editor gives students a text editor of 15 lines. graderinfo is shown only to markers; when your test has a model answer for the question, it is put there.

Pictures

<questiontext format="html">
  <text><![CDATA[<p>… How long is the longest side?</p>
    <p><img src="@@PLUGINFILE@@/1794549682_5eb271d75878cad6_001.png" alt="" /></p>]]></text>
  <file name="1794549682_5eb271d75878cad6_001.png" path="/" encoding="base64">iVBORw0KGgo…</file>
</questiontext>

The picture travels inside the file. The <file> element holds the image encoded as base64 text, and the HTML points to it with @@PLUGINFILE@@, which Moodle replaces with the address of the stored file after import. A link to a picture on another website would work too, but it breaks when that site changes.

Formulas

<p>What are the solutions of the equation \(x^2-5x+6=0\)?</p>

A Word equation is written as TeX between \( and \). Moodle shows it as a formula through its MathJax filter, which is on by default. If students see the code instead, ask the site administrator to enable the MathJax filter for the course.

Importing the example

1. Open a course you can test in and go to its question bank (in the course's More menu: Question bank, or Question banks in recent versions).
2. Choose Import, select Moodle XML format, drop the .xml file into the box and click Import.
3. Moodle lists the questions it read. Click Continue; they are in the category moodle-xml-example and its four parts.
4. Preview question 3 (the picture) and question 4 (the formula) to check that both display.

Editing a file by hand

• Use a plain-text editor that saves UTF-8, not a word processor.
• Keep HTML inside CDATA. Outside it, write < for < and & for &.
• A single unclosed tag makes Moodle reject the whole file. Open it in a browser first: a broken file shows the line of the error.
• Import into a test course before the real one, and preview a few questions.

Make one from your own Word test

Write the test in Word as usual, with the rules in the Word test format cheat sheet, then open the free quiz converter, upload the file and click Moodle XML (.xml). No account is needed. The converter lists anything Moodle does differently before you download, for example a multiple-response question that Moodle scores with partial credit. The full walkthrough is in how to import a Word test into Moodle.

Questions

Is Moodle XML the same as GIFT or Aiken? No. GIFT and Aiken are plain-text formats that people type by hand; they cannot carry pictures inside the file, and Aiken only knows single-answer multiple choice. Moodle XML is longer but carries everything.

Can other systems read Moodle XML? Some can, but it is Moodle's own format. For systems that import QTI 2.1 packages, the converter also makes one. Canvas Classic Quizzes expects QTI 1.2, so it does not read that package.

Why does Moodle count more questions than my test has? Because some questions become several Moodle questions: each true/false statement is its own question, and a reading passage becomes a description item before its questions. The converter tells you how many Moodle questions it wrote.

Will the example work in other languages? Yes. The example is available in every language of this site; switch the language at the top of the page to download it.