flalingo/JSON_STRUCTURE.md

JSON Structure Documentation

Diese Dokumentation erklärt die JSON-Struktur für Lernpfade in der Flalingo-Anwendung.

Übersicht

Ein Lernpfad (Path) besteht aus mehreren hierarchischen Elementen:

• Path: Der Hauptcontainer für einen Lernkurs
• Metadata: Versionierung und Zeitstempel
• Nodes: Lerneinheiten innerhalb des Pfads
• Exercises: Einzelne Übungen innerhalb der Nodes

JSON Schema

Path (Hauptstruktur)

{
  "id": "string",           // Eindeutige Pfad-ID
  "title": "string",        // Titel des Lernpfads
  "description": "string",  // Beschreibung des Pfads
  "metadata": [...],        // Array von Metadata-Objekten
  "nodes": [...]           // Array von Node-Objekten
}

Metadata

{
  "path_id": "string",      // Referenz zur Pfad-ID
  "version": "string",      // Versionsnummer (z.B. "1.0.0")
  "created_at": "string",   // ISO 8601 Timestamp
  "updated_at": "string"    // ISO 8601 Timestamp
}

Node (Lerneinheit)

{
  "id": number,             // Eindeutige Node-ID (Zahl)
  "title": "string",        // Titel der Lerneinheit
  "description": "string",  // Beschreibung der Einheit
  "path_id": "string",      // Referenz zur übergeordneten Pfad-ID
  "exercises": [...]        // Array von Exercise-Objekten
}

Exercise (Übung)

{
  "id": number,             // Eindeutige Exercise-ID (Zahl)
  "ex_type": "string",      // Typ der Übung (siehe Exercise-Typen)
  "content": "string",      // JSON-String mit übungsspezifischen Daten
  "node_id": number         // Referenz zur übergeordneten Node-ID
}

Exercise-Typen

Das content-Feld enthält einen JSON-String, dessen Struktur je nach ex_type variiert:

vocabulary

Vokabel-Lernkarten

{
  "word": "hola",
  "translation": "hallo",
  "audio": "hola.mp3",
  "image": "greeting.jpg",
  "context": "informal greeting",
  "gender": "feminine",     // für gendered Sprachen
  "type": "greeting"        // Kategorie
}

multiple_choice

Multiple-Choice Fragen

{
  "question": "Was bedeutet 'apple'?",
  "options": ["Apfel", "Birne", "Orange", "Banane"],
  "correct": 0,             // Index der richtigen Antwort
  "explanation": "Apple = Apfel auf Deutsch"
}

fill_blank

Lückentexte

{
  "sentence": "The cat ___ on the table",
  "answer": "is",
  "options": ["is", "are", "was", "were"],  // optional
  "hint": "Verb 'to be' in 3rd person singular"
}

translation

Übersetzungsübungen

{
  "source": "I am happy",
  "target": "Ich bin glücklich",
  "language_pair": "en-de",
  "hints": ["I = Ich", "am = bin", "happy = glücklich"]
}

grammar

Grammatik-Erklärungen und -Übungen

{
  "rule": "Present tense of 'ser'",
  "explanation": "Das Verb 'ser' (sein) im Präsens",
  "examples": ["Yo soy estudiante", "Tú eres profesor"],
  "conjugations": [
    {"person": "yo", "form": "soy"},
    {"person": "tú", "form": "eres"}
  ]
}

pronunciation

Ausspracheübungen

{
  "phrase": "Me llamo...",
  "phonetic": "me ˈʎamo",
  "audio": "me_llamo.mp3",
  "tip": "Das 'll' wird wie 'j' ausgesprochen",
  "speed": "normal"         // slow, normal, fast
}

matching

Zuordnungsübungen

{
  "pairs": [
    {"left": "hermano", "right": "Bruder"},
    {"left": "hermana", "right": "Schwester"},
    {"left": "padre", "right": "Vater"}
  ],
  "instruction": "Ordne die spanischen Wörter den deutschen zu"
}

listening

Hörverständnisübungen

{
  "audio": "dialogue.mp3",
  "question": "Was sagt die Frau?",
  "options": ["Ich bin müde", "Ich bin hungrig", "Ich bin glücklich"],
  "correct": 1,
  "transcript": "Tengo hambre"  // optional
}

sentence_building

Sätze zusammensetzen

{
  "words": ["Yo", "soy", "estudiante", "de", "medicina"],
  "correct_order": ["Yo", "soy", "estudiante", "de", "medicina"],
  "translation": "Ich bin Medizinstudent",
  "shuffled": true          // Wörter werden gemischt dargestellt
}

image_selection

Bildauswahl

{
  "instruction": "Wähle das rote Auto",
  "images": ["red_car.jpg", "blue_car.jpg", "green_car.jpg"],
  "correct": "red_car.jpg",
  "audio": "red_car_audio.mp3"  // optional
}

conversation

Dialogübungen

{
  "scenario": "Im Restaurant bestellen",
  "dialogue": [
    {"speaker": "waiter", "text": "¿Qué desea ordenar?"},
    {"speaker": "customer", "text": "Quiero una pizza, por favor"},
    {"speaker": "waiter", "text": "¿Algo para beber?"}
  ],
  "user_role": "customer",
  "context": "formal restaurant setting"
}

Datentypen und Validierung

Pflichtfelder

• Alle id Felder sind erforderlich und müssen eindeutig sein
• title und description sind immer erforderlich
• content muss ein gültiger JSON-String sein

Referenzielle Integrität

• metadata.path_id muss mit path.id übereinstimmen
• node.path_id muss mit path.id übereinstimmen
• exercise.node_id muss mit node.id übereinstimmen

Zeitstempel

Alle Zeitstempel müssen im ISO 8601 Format vorliegen:

"2024-01-20T10:30:00Z"

Beispiel-Dateien

• example_path.json - Vollständiger Spanisch-Anfängerkurs
• example_path_simple.json - Vereinfachtes Beispiel mit grundlegenden Typen

Erweiterbarkeit

Das System ist so konzipiert, dass neue Exercise-Typen einfach hinzugefügt werden können:

1. Neuen ex_type definieren
2. Entsprechende content-Struktur dokumentieren
3. Repository-Layer unterstützt automatisch neue Typen