Import a quiz

QuizDock imports three kinds of file from the dashboard: its own bundle (.zip), its own quiz file (quiz.json) and a Kahoot spreadsheet (.xlsx). For anything else (a PDF, screenshots, another tool’s export) a chatbot can write the quiz.json for you. Every import creates a new draft in your bank; nothing you already have is changed.

Import from the dashboard

In My quizzes, choose New quiz → Import a file….
Pick a .zip, .json or .xlsx file.
The quiz opens in the editor as a new Draft. Check it, then Publish (ready).

File	What it holds
`.zip`, a QuizDock bundle	The whole quiz, with its media and its theme, as Export writes it.
`.json`, a `quiz.json`	The quiz’s text only: questions, answers, slides, no media.
`.xlsx`, a Kahoot spreadsheet	Questions written in Kahoot’s official template.

A file is limited to 50 MB by default; whoever runs your instance can change it. An invalid file is refused as a whole. An error in a question or a slide names the item and the field at fault: “Item 3 of the bundle is invalid (…).” A file that cannot be read, or whose structure is not QuizDock’s, gets “Not a QuizDock bundle (quiz.json + media/, zipped).”

Kahoot spreadsheet

Use Kahoot’s official spreadsheet template: one sheet, headers on row 8, questions from row 9. Delete the template’s example question if you do not want it. The file name becomes the draft’s title.

What comes across:

the wording, the order of the answers and the correct answers;
the time limits, from 5 to 240 seconds (an empty cell gives the default 20);
one correct answer becomes Multiple choice (single answer), several become Multiple choice (multiple answers).

What does not:

pictures, sounds and links: they are not read or fetched;
the language and the licence: the draft takes the instance’s language and has no licence. Check both in Settings before publishing or sharing.

The editor shows a report on top, such as “12 questions imported from Kahoot.” and “Pictures and sounds are not brought over.” A row missing its question, answers or correct answer still comes in, as a question marked Unfinished: the quiz cannot be published until it is complete. A row is left out, and reported as “Row 14 left out: …”, only when QuizDock cannot hold it: a time limit outside 5–240 seconds, a formula cell, or a text too long for QuizDock. When no row can be converted, no draft is created.

A Kahoot quiz’s web address is not an import source: the spreadsheet template is. To bring an existing kahoot, use the chatbot conversion below.

Move a quiz with a bundle

A bundle carries a whole quiz from one bank or one instance to another.

In the editor, open More and choose Export. The browser downloads a file named after the quiz, such as discover-france.quizdock.zip: the quiz file, its media and its theme.
On the other side, choose New quiz → Import a file… in My quizzes and pick that file.

The import is always a new draft with its own copy of the media; the original quiz is not linked to it. Past sessions and results do not travel with a bundle.

Export for publication is a different file, checked for the community store; see Templates and community.

Convert from another tool with a chatbot

For a PDF, screenshots, another spreadsheet or plain text, a chatbot can do the conversion: give it what you have, the prompt below and the quiz format guide, and it writes a quiz.json that QuizDock imports. It works from almost anything:

a PDF: on Kahoot, print the kahoot’s page from the browser and choose Save as PDF; it holds the questions and the answers, with the right one marked;
screenshots of each question with its answers, when nothing can be printed or exported; a phone photo of a quiz on paper works too (the chatbot has to read images: most current ones do);
a spreadsheet with one question per row;
text: a Word document, notes, a list pasted as is.

Step by step

Open a chatbot and paste the prompt below. Attach the format guide (download it, or paste it below the prompt), then your quiz. Several screenshots in one message are fine.
The chatbot answers with a JSON block and a short To check list. Save the block as a file ending in .json: copy it into a text editor, or download it when the chatbot offers a file.
In QuizDock, choose New quiz → Import a file… in My quizzes and pick the file. The quiz opens as a new draft.
Read the To check list, then go through the quiz before playing it:
- the correct answers: a chatbot can misread a mark, or guess one the source did not show;
- the pictures: none are imported; add your own from the media library;
- the time limits: one over QuizDock’s maximum is shortened.

If the import is refused, paste the message back to the chatbot and ask for a corrected file. An error in a question names the item and the field at fault; “Not a QuizDock bundle (…)” means the file is not JSON or its structure is wrong.

The prompt

Copy it whole. It is in English, the language chatbots follow best; the quiz keeps its own language. The format itself is in the guide: the prompt only says how to convert.

Convert the quiz I give you (PDF, screenshots, spreadsheet or text) into a QuizDock quiz file, following the "QuizDock quiz file — format guide" I attach or paste below, exactly.

Answer with ONE JSON code block, then a short "To check" list. Nothing else.

Pick each question's type from what the source asks the players to do:
- one correct answer: single_choice; several: multiple_choice; true or false: true_false;
- a typed answer: text_input, with every spelling the source accepts;
- a number or a slider: numeric, with the source's margin as the tolerance;
- answers to put in order (a puzzle): ordering;
- a survey with no correct answer: poll;
- word clouds, open-ended or brainstorm questions have no equivalent: leave them out.
A page of information between questions becomes a slide.

Rules:
- Keep the source's wording, order and language. Do not translate, shorten or improve anything.
- Keep the source's time limits and double or no points.
- No images, sounds or videos. When a question needs its picture to make sense, keep the question.
- Never invent a correct answer. For each question, look at whether the source marks the right answer (a tick, a colour, bold, a key). When it does not, choose the one you are sure of, or make it a poll if you are not; either way, list the question under "To check", even when the answer seems obvious.
- Before answering, go through the guide's checklist and fix what fails. Every change made to fit a limit (a shorter time, a shortened text, answers dropped) goes under "To check".

"To check" lists, by question number in the source: questions left out and why, answers you chose yourself, pictures that were lost, limits you had to change (time, length, number of answers). Write "Nothing" when the list is empty.

What comes across

In the source	In QuizDock
Quiz, one correct answer	Multiple choice (single answer)
Quiz, several correct answers	Multiple choice (multiple answers)
True or false	True / False
Type answer	Text input, with the accepted spellings
Slider	Numeric, with its margin as the tolerance
Puzzle	Reorder
Poll	Poll (no points)
Slide	A slide with a heading and a text
Double points / no points	The same, per question
Time limit	The same, within 5 to 240 seconds

Word clouds, open-ended and brainstorm questions have no equivalent: they are left out and listed under To check. Image choice questions are not part of a text-only conversion: add them in the editor.

Images and sounds stay behind on purpose. A quiz.json carries no media, and the pictures of a Kahoot quiz often come from licensed image banks: they are not yours to copy. The chatbot notes which questions had one, and you add your own; the media library links to free libraries when the instance offers them.

Whoever runs your instance can also check a file before it is imported, with the command-line tool or a local connector for AI assistants; see CLI.

The quiz format guide

This guide is generated from the importer of the current release, so it always describes the file QuizDock accepts today.

How to write a QuizDock quiz file (quiz.json) that the importer accepts, text only. It writes manifest version 3 of the format quizdock/quiz; the structure is also published as a JSON Schema: https://raw.githubusercontent.com/quizdock/quizdock/main/schema/quiz-bundle.v3.json

The file

{ "format": "quizdock/quiz", "version": 3, "quiz": { … }, "items": [ … ] }

quiz.title — required, at most 200 characters.
quiz.description — optional, Markdown.
quiz.language — the BCP 47 code of the quiz’s language (en, fr, es, zh-TW…).
items — the questions and slides, in playing order, at most 500.

Questions

{ "kind": "question", "type": "…", "prompt": "…", … }

Every question:

prompt — required, Markdown, at most 1000 characters.
timeLimitS — whole seconds, 5 to 240; 20 when left out.
pointsMode — standard (faster answers score more), double (twice that), none (no points), fixed (full points whatever the speed); standard when left out.
scoring — standard when left out; also partial for multiple_choice, lenient for text_input, closest for numeric, partial for ordering.
answerExplanation — optional, Markdown, shown at the reveal, at most 2000 characters.

type, and what each one asks for:

single_choice — one correct answer. 2 to 8 options, exactly one with "isCorrect": true.
multiple_choice — several correct answers. 2 to 8 options, at least one with "isCorrect": true.
true_false — true or false. Exactly 2 options, “True” then “False” written in the quiz’s language, exactly one with "isCorrect": true.
text_input — the player types the answer. No options; acceptedAnswers lists the accepted spellings (case and accents are ignored when comparing).
numeric — the answer is a number (a slider, a year, a count). No options; numericValue is the right number, numericTolerance the margin accepted on either side (0 = exact).
ordering — answers to put in order (a puzzle). 2 to 8 options, in any display order, each with correctOrderIndex: its place in the right order, counted from 0, each place used once.
poll — a survey, no correct answer and no points. 2 to 8 options, none with isCorrect.
acceptedAnswers — 1 to 200 characters each, at most 20 (plain strings).
numericTolerance — 0 or more.

Options

{ "text": "…", "color": "…", "shape": "…", "isCorrect": true }

text — Markdown, at most 500 characters.
isCorrect — true on the correct ones; leave it out on the others.
correctOrderIndex — ordering questions only.
color and shape go by position, never repeated within a question:

green / square
red / triangle
blue / diamond
yellow / circle
purple / star
orange / hexagon
pink / heart
teal / cross

Slides

A page of information between questions: { "kind": "slide", "blocks": [ … ] }, with at least one block.

{ "type": "heading", "id": "h1", "text": "…", "level": 1 } — at most 200 characters; level 1 or 2.
{ "type": "text", "id": "t1", "md": "…" } — Markdown, at most 5000 characters.

Each id is unique within its slide, at most 64 characters.

Left out

A converted quiz carries no media and no layout: the author adds them in QuizDock. Never write these fields (a zipped export carries them, with its files):

the file: media, theme;
quiz: feedbackEnabled, mediaTailS, loudnessTargetLufs, audioTarget, cover, slug, namespace, revision, updatedAt, domain, tags, license;
a question: media, audio, backgroundImage, backgroundGradient, background, textTone, textOutline, revealDelayS, audioTarget, waveformSize, mediaPosition, timerAfterMedia, multiSelect;
an option: media, alt;
a slide: backgroundImage, backgroundGradient, background, textTone, textOutline, video, videoLoop, videoSound, audio, waveformSize, audioTarget, displayDelayS; block types image, columns;
Markdown images (![…](…)) anywhere.

Writing it

Valid JSON: double quotes, no comments, no trailing commas.
Markdown is read in prompts, options, explanations and slide text: a literal * or _ is written \\* or \\_ inside the JSON string.
An invalid file is refused as a whole. An item outside the rules is named (counted from 1) with the field at fault; a file that is not a quiz at all is refused as such.
A step not finished yet (no right answer ticked, a picture without its alt text) does not stop the import: the quiz arrives as a draft, the step marked unfinished.

Checklist

Go through it before handing the file over: a time, a length or a count outside these rules makes the whole import fail; the answers, if left unfinished, make a draft to finish in the editor.

Every timeLimitS is a whole number from 5 to 240: a longer time is written 240.
Every prompt has 1000 characters at most, every option text 500.
Every question with options has 2 to 8 of them.
single_choice and true_false: exactly one "isCorrect": true; multiple_choice: at least one; poll: none.
ordering: the correctOrderIndex values are 0 to n-1, each once.
text_input has acceptedAnswers and no options; numeric has numericValue and numericTolerance, and no options.
Option color and shape follow the positions listed under Options.
No field from Left out, no Markdown image.

Example

{
  "format": "quizdock/quiz",
  "version": 3,
  "quiz": {
    "title": "Space",
    "language": "en"
  },
  "items": [
    {
      "kind": "slide",
      "blocks": [
        {
          "type": "heading",
          "id": "h1",
          "text": "Round 1: the planets",
          "level": 1
        },
        {
          "type": "text",
          "id": "t1",
          "md": "Seven questions, **double points** on the galaxy."
        }
      ]
    },
    {
      "kind": "question",
      "type": "single_choice",
      "prompt": "Which planet is the largest?",
      "timeLimitS": 20,
      "options": [
        {
          "text": "Mars",
          "color": "green",
          "shape": "square"
        },
        {
          "text": "Jupiter",
          "color": "red",
          "shape": "triangle",
          "isCorrect": true
        },
        {
          "text": "Venus",
          "color": "blue",
          "shape": "diamond"
        },
        {
          "text": "Mercury",
          "color": "yellow",
          "shape": "circle"
        }
      ]
    },
    {
      "kind": "question",
      "type": "multiple_choice",
      "prompt": "Which of these are gas giants?",
      "timeLimitS": 30,
      "options": [
        {
          "text": "Jupiter",
          "color": "green",
          "shape": "square",
          "isCorrect": true
        },
        {
          "text": "Earth",
          "color": "red",
          "shape": "triangle"
        },
        {
          "text": "Saturn",
          "color": "blue",
          "shape": "diamond",
          "isCorrect": true
        }
      ]
    },
    {
      "kind": "question",
      "type": "true_false",
      "prompt": "The Sun is a star.",
      "timeLimitS": 10,
      "answerExplanation": "A yellow dwarf, about 4.6 billion years old.",
      "options": [
        {
          "text": "True",
          "color": "green",
          "shape": "square",
          "isCorrect": true
        },
        {
          "text": "False",
          "color": "red",
          "shape": "triangle"
        }
      ]
    },
    {
      "kind": "question",
      "type": "text_input",
      "prompt": "What is the name of our galaxy?",
      "pointsMode": "double",
      "acceptedAnswers": [
        "Milky Way",
        "The Milky Way"
      ]
    },
    {
      "kind": "question",
      "type": "numeric",
      "prompt": "In which year did a human first walk on the Moon?",
      "numericValue": 1969,
      "numericTolerance": 0
    },
    {
      "kind": "question",
      "type": "ordering",
      "prompt": "Put these planets in order, closest to the Sun first.",
      "timeLimitS": 60,
      "options": [
        {
          "text": "Earth",
          "color": "green",
          "shape": "square",
          "correctOrderIndex": 2
        },
        {
          "text": "Mercury",
          "color": "red",
          "shape": "triangle",
          "correctOrderIndex": 0
        },
        {
          "text": "Venus",
          "color": "blue",
          "shape": "diamond",
          "correctOrderIndex": 1
        }
      ]
    },
    {
      "kind": "question",
      "type": "poll",
      "prompt": "Which planet would you visit?",
      "options": [
        {
          "text": "Mars",
          "color": "green",
          "shape": "square"
        },
        {
          "text": "Saturn",
          "color": "red",
          "shape": "triangle"
        },
        {
          "text": "Neptune",
          "color": "blue",
          "shape": "diamond"
        }
      ]
    }
  ]
}

Questions

Can I import a CSV file?

No. QuizDock imports its own bundle and quiz.json, and Kahoot’s .xlsx template. For a CSV or any other spreadsheet, use the chatbot conversion above.

Does importing a quiz bring its results?

No. A bundle carries the quiz and its media. Sessions, results and player feedback stay on the instance where the quiz was played.

Can I update an existing quiz by importing it again?

No. Every import creates a new draft. Delete or archive the old quiz once the new one is checked.