Documentation

Dokumentation

Quiz exchange format

Austauschformat für Quizze

QuizLane imports and exports quizzes as ZIP files containing quizlane.json plus media files – or as a simple CSV table you can edit in Excel, Numbers or Google Sheets.

QuizLane importiert und exportiert Quizze als ZIP-Datei mit quizlane.json und Mediendateien – oder als einfache CSV-Tabelle, die du in Excel, Numbers oder Google Tabellen bearbeiten kannst.

1. ZIP package

1. ZIP-Paket

• The ZIP contains exactly one quizlane.json in its root and optionally media files.
• Questions refer to media by relative paths, usually media/<sha256>.<ext> (content-addressed, so the same file is stored only once). Any other relative path such as media/pike.jpg works as well.
• Images: jpg, jpeg, png, webp, gif (max. 15 MB). Videos: mp4, m4v, mov (max. 200 MB). The file type is checked by its content, not only by its name.
• Text-only quizzes need no media – a ZIP with just quizlane.json is fine.
• A quiz refers to its knowledge modules instead of containing questions directly. Modules with the same ID are recognised on import and not created twice.
• Empty values (null, empty texts and lists) are omitted on export. Unknown fields are ignored.

• Das ZIP enthält genau eine quizlane.json im Wurzelverzeichnis und bei Bedarf Mediendateien.
• Fragen verweisen über relative Pfade auf Medien, im Normalfall media/<sha256>.<endung> (inhaltsadressiert – dieselbe Datei liegt nur einmal vor). Andere relative Pfade wie media/hecht.jpg funktionieren ebenso.
• Bilder: jpg, jpeg, png, webp, gif (max. 15 MB). Videos: mp4, m4v, mov (max. 200 MB). Das Format wird am Inhalt geprüft, nicht nur am Namen.
• Reine Text-Quizze brauchen keine Medien – ein ZIP nur mit quizlane.json genügt.
• Ein Quiz verweist auf seine Wissensbausteine, statt die Fragen direkt zu enthalten. Bausteine mit gleicher Kennung werden beim Import erkannt und nicht doppelt angelegt.
• Leere Werte (null, leere Texte und Listen) werden beim Export weggelassen. Unbekannte Felder werden ignoriert.

2. quizlane.json

2. quizlane.json

Quiz

Module (knowledge module)(Wissensbaustein)

Question

MediaItem & Attribution

3. Question types

3. Fragetypen

Example

Beispiel

{
  "format": "quizlane",
  "formatVersion": 1,
  "quiz": {
    "id": "quiz-fishing-nrw",
    "title": "Fischerprüfung NRW",
    "language": "de",
    "languages": ["en"],
    "titleI18n": { "en": "Fishing licence exam NRW" },
    "modules": [{ "id": "module-fish" }],
    "exam": { "rules": [{ "moduleId": "module-fish", "count": 2, "minCorrect": 1 }], "passPercent": 60 }
  },
  "modules": [{
    "id": "module-fish",
    "title": "Fischkunde",
    "catalogs": [{
      "id": "catalog-fish", "title": "Fischarten",
      "entries": [
        { "id": "fish-pike", "text": "Hecht", "i18n": { "en": "Pike" } },
        { "id": "fish-zander", "text": "Zander", "i18n": { "en": "Zander" } }
      ]
    }],
    "questions": [
      { "id": "q1", "type": "catalog", "prompt": { "image": "media/pike.jpg" },
        "catalogId": "catalog-fish", "correct": ["fish-pike"] },
      { "id": "q2", "type": "text",
        "prompt": { "text": "Wie heißt der Raubfisch mit „Entenschnabel“?", "i18n": { "en": "Which predator has a “duck bill”?" } },
        "text": { "accepted": ["Hecht"], "i18n": { "en": ["Pike", "Northern pike"] } },
        "explanation": "Der Hecht hat ein entenschnabelförmiges Maul." }
    ],
    "media": [{ "path": "media/pike.jpg", "kind": "image", "mime": "image/jpeg", "rightsConfirmed": true,
                "attribution": { "author": "M. Muster", "license": "CC BY 4.0" } }]
  }]
}

4. CSV (spreadsheet)

4. CSV (Tabelle)

• One row per question. Separator ,, ; or tab is detected automatically; quoted fields follow RFC 4180. Several values in one cell are separated by |.
• Optional lines before the header: # title: …, # description: …, # language: de, # path: chapters (chapters build on each other in order).
• Translations as extra columns <column>@<lang>, e.g. question@en, options@en, correct@en, explanation@en, hint@en, chapter@en, module@en.
• Media: put the path (e.g. media/pike.jpg) into the cell and the file into the ZIP. Options that look like image paths become image options.
• Column names are case-insensitive; German names work too (Frage, Antworten, Lösung, Kapitel, Erklärung …). Invalid rows are reported, valid rows are imported anyway.

• Eine Zeile pro Frage. Trennzeichen ,, ; oder Tab werden erkannt; Felder in Anführungszeichen nach RFC 4180. Mehrere Werte in einer Zelle trennt |.
• Optionale Zeilen vor der Kopfzeile: # title: …, # description: …, # language: de, # path: chapters (Kapitel bauen in Reihenfolge aufeinander auf).
• Übersetzungen als zusätzliche Spalten <spalte>@<sprache>, z. B. question@en, options@en, correct@en, explanation@en, hint@en, chapter@en, module@en.
• Medien: Pfad (z. B. media/hecht.jpg) in die Zelle, Datei mit ins ZIP. Antworten, die wie Bildpfade aussehen, werden zu Bildantworten.
• Spaltennamen sind unabhängig von Groß/klein; deutsche Namen gehen auch (Frage, Antworten, Lösung, Kapitel, Erklärung …). Fehlerhafte Zeilen werden gemeldet, gültige trotzdem übernommen.

# title: My first quiz
# language: en
type,chapter,question,image,options,correct,catalog,explanation,question@de,options@de,correct@de
single,Basics,What is the capital of France?,,Paris|Lyon|Marseille,Paris,,Since 987.,Was ist die Hauptstadt von Frankreich?,Paris|Lyon|Marseille,
text,Basics,What is the capital of Iceland?,,,Reykjavík|Reykjavik,,,Wie heißt die Hauptstadt Islands?,,Reykjavík|Reykjavik
catalog,Fish,Which fish is this?,media/pike.jpg,Perch|Carp,Pike,Fish species,,Welcher Fisch ist das?,,Hecht

5. Checks on import

5. Prüfung beim Import

Before a quiz is accepted, the app checks structure, file references and media formats and shows understandable messages. Errors include, among others: missing title (quiz.titleMissing), missing module (quiz.moduleMissing), empty question (question.promptEmpty), fewer than two options (question.tooFewOptions), no or unknown solution (question.noCorrect, question.correctUnknown), single choice with more than one solution (question.singleNeedsOne), missing catalogue (question.catalogMissing), text question without accepted answer (question.textNoAnswer), free answer without model solution (question.modelAnswerMissing), duplicate IDs (id.duplicate), unsupported or missing media (media.unsupported, media.missing), and for publishing unconfirmed media rights (media.rightsUnconfirmed). Incomplete translations are only a warning (translation.incomplete).

Bevor ein Quiz übernommen wird, prüft die App Datenstruktur, Dateiverweise und Medienformate und zeigt verständliche Meldungen. Fehler sind u. a.: fehlender Titel (quiz.titleMissing), fehlender Baustein (quiz.moduleMissing), leere Frage (question.promptEmpty), weniger als zwei Antworten (question.tooFewOptions), keine oder unbekannte Lösung (question.noCorrect, question.correctUnknown), Einfachauswahl mit mehr als einer Lösung (question.singleNeedsOne), fehlender Katalog (question.catalogMissing), Texteingabe ohne zulässige Antwort (question.textNoAnswer), freie Antwort ohne Musterlösung (question.modelAnswerMissing), doppelte Kennungen (id.duplicate), nicht unterstützte oder fehlende Medien (media.unsupported, media.missing) und für die Veröffentlichung unbestätigte Medienrechte (media.rightsUnconfirmed). Unvollständige Übersetzungen sind nur ein Hinweis (translation.incomplete).