Format JSON Import Latihan Soal: Panduan Lengkap untuk Guru

Selain lewat MCP, PapanAjar menyediakan cara yang lebih sederhana untuk membuat latihan soal: impor JSON. Guru cukup membuka /dashboard/latihan/import, menempel JSON hasil ChatGPT, memeriksa pratinjau, lalu menekan Impor.

Kabar baiknya, format JSON ini sama persis dengan yang dipakai MCP dan REST API. Jadi sekali kamu memahami formatnya, kamu bisa memakainya di semua jalur tanpa perlu menyesuaikan apa pun.

Struktur dasar JSON

Satu payload JSON terdiri dari meta latihan (judul, deskripsi, durasi, dan pengaturan), daftar stimuli atau wacana, serta daftar soal. Soal boleh berada di dalam sebuah stimulus, atau langsung di root jika tidak memakai wacana.

{
  "title": "Latihan TKA Matematika",
  "description": "Latihan persiapan TKA kelas 12.",
  "duration_minutes": 60,
  "show_score": true,
  "student_code_mode": "open",
  "shuffle_questions": false,
  "shuffle_options": false,
  "stimuli": [
    {
      "title": "Bacaan 1",
      "content_md": "Teks wacana atau konteks soal...",
      "questions": [
        {
          "type": "multiple_choice",
          "prompt": "Pernyataan yang benar adalah ...",
          "points": 1,
          "options": [
            { "id": "A", "text": "Pilihan A" },
            { "id": "B", "text": "Pilihan B" },
            { "id": "C", "text": "Pilihan C" }
          ],
          "answer_key": { "correct": ["A"] }
        }
      ]
    }
  ],
  "questions": [
    {
      "type": "short_answer",
      "prompt": "Hasil dari 3 + 4 adalah ...",
      "points": 1,
      "answer_key": { "accepted": ["7"], "numeric": true, "tolerance": 0 }
    }
  ]
}

Semua kolom meta bersifat opsional kecuali title. Jika tidak diisi, nilai bawaan akan dipakai—misalnya show_score bernilai true, student_code_mode bernilai closed, dan scoring_mode bernilai scale_100.

Mengenal kolom meta

• title — judul latihan (wajib).
• description — deskripsi singkat, boleh berisi konteks materi.
• collection_id — UUID koleksi, atau null agar tampil di level-1.
• duration_minutes — durasi timer CBT; kosongkan jika tanpa batas.
• scoring_mode — raw atau scale_100 (default).
• show_score — tampilkan nilai ke siswa setelah submit.
• shuffle_questions & shuffle_options — acak soal dan opsi.
• student_code_mode — closed (kode terdaftar) atau open (bebas).
• is_published — terbitkan langsung atau simpan sebagai draf.

Tipe soal yang didukung

PapanAjar hanya memakai soal yang bisa dinilai otomatis, sehingga nilai langsung keluar saat siswa menekan submit. Ada empat tipe yang bisa dipakai.

Pilihan ganda (satu jawaban)

Isi 2–5 opsi dengan id unik, lalu tentukan tepat satu kunci pada answer_key.correct.

{
  "type": "multiple_choice",
  "prompt": "Pernyataan yang benar adalah ...",
  "points": 1,
  "options": [
    { "id": "A", "text": "Pilihan A" },
    { "id": "B", "text": "Pilihan B" },
    { "id": "C", "text": "Pilihan C" }
  ],
  "answer_key": { "correct": ["A"] }
}

Pilihan ganda kompleks (jawaban lebih dari satu)

Boleh 2–8 opsi dan minimal satu kunci. Gunakan scoring.mode partial_proportional agar nilai diberikan proporsional per jawaban benar.

{
  "type": "multiple_choice_complex",
  "prompt": "Pilih semua jawaban yang benar.",
  "points": 2,
  "options": [
    { "id": "A", "text": "Pilihan A" },
    { "id": "B", "text": "Pilihan B" },
    { "id": "C", "text": "Pilihan C" }
  ],
  "answer_key": { "correct": ["A", "C"] },
  "scoring": { "mode": "partial_proportional" }
}

Menjodohkan

Opsi dibagi menjadi left dan right. Kunci jawaban ditulis sebagai daftar pairs, dan setiap id harus ada di kolomnya masing-masing.

{
  "type": "matching",
  "prompt": "Jodohkan istilah dengan definisinya.",
  "points": 3,
  "options": {
    "left": [
      { "id": "L1", "text": "Sisi miring" },
      { "id": "L2", "text": "Sudut 90 derajat" }
    ],
    "right": [
      { "id": "R1", "text": "Hipotenusa" },
      { "id": "R2", "text": "Siku-siku" }
    ]
  },
  "answer_key": {
    "pairs": [
      { "left": "L1", "right": "R1" },
      { "left": "L2", "right": "R2" }
    ]
  },
  "scoring": { "mode": "partial_proportional" }
}

Isian singkat

Tulis semua jawaban yang dianggap benar pada accepted. Untuk jawaban angka, aktifkan numeric dan atur tolerance bila perlu.

{
  "type": "short_answer",
  "prompt": "Ibu kota Indonesia adalah ...",
  "points": 1,
  "answer_key": { "accepted": ["Jakarta", "DKI Jakarta"] }
}

{
  "type": "short_answer",
  "prompt": "Hasil dari 12 ÷ 4 adalah ...",
  "points": 1,
  "answer_key": { "accepted": ["3"], "numeric": true, "tolerance": 0.5 }
}

Aturan validasi yang perlu diperhatikan

• type harus salah satu dari empat tipe di atas—tipe tak dikenal akan ditolak.
• multiple_choice membutuhkan 2–5 opsi dan tepat 1 kunci.
• multiple_choice_complex membutuhkan 2–8 opsi dan minimal 1 kunci.
• matching membutuhkan minimal 1 pasangan, dan id pada kunci harus cocok dengan options.
• short_answer membutuhkan minimal 1 jawaban pada accepted.
• points harus lebih besar dari 0 (bawaan 1).
• Maksimal 200 soal per impor dan ukuran payload maksimal 1 MB.

Jika ada kesalahan, pesan errornya spesifik per soal—misalnya stimuli.0.questions.2.answer_key.correct.0: kunci "E" tidak ada di options. Kamu bisa langsung memperbaiki bagian yang ditunjuk.

Tips membuat soal lewat ChatGPT

Kunci agar hasil ChatGPT langsung valid adalah menjelaskan format yang diinginkan. Gunakan tombol Salin format di halaman impor, atau mulai dengan prompt seperti berikut.

Buatkan 1 paket latihan soal TKA Matematika kelas 12 dalam format JSON
sesuai skema PapanAjar. Gunakan 1 wacana dan 5 soal pilihan ganda.
Sertakan field: title, description, duration_minutes, show_score,
student_code_mode, stimuli[].questions[]. Setiap soal punya type, prompt,
points, options, dan answer_key. Output hanya JSON, tanpa penjelasan.

Setelah JSON muncul, salin, tempel ke kolom impor, lalu klik Validasi & pratinjau. Periksa jumlah soal dan total bobot, kemudian tekan Impor sekarang.

Mulai dari satu wacana dan beberapa soal pilihan ganda. Setelah terbiasa, kamu bisa memanfaatkan pilihan ganda kompleks, menjodohkan, dan isian singkat untuk latihan yang lebih kaya.