問題集の作り方（CSV と JSON）

Ultra Practicebook に自分の問題を入れる方法は、画面で一問ずつ作る、CSV を取り込む、JSON を取り込む、の三つです。このページは、あとから自分で直せるように、列と項目の意味を文章で残したものです。アプリの中のヒントと同じ規則です。

どの形式を選ぶか

一問だけ試すなら、画面の手入力が早いです。すでに表計算ソフトに単語と意味が並んでいるなら CSV です。プログラムからまとめて出す、ネストした選択肢をそのまま持ちたい、なら JSON です。どちらで入れても、クイズに載る情報は同じです。問題文、形式、選択肢、正解、解説、難易度、分類です。

ファイルは UTF-8 にしてください。Excel で「CSV UTF-8」以外の ANSI 保存にすると、日本語が崩れます。崩れた状態で取り込むと、問題文が文字化けしたまま保存されます。

CSV の列

1行目は、次の列名をこの順で書きます。

question_text,question_type,option_1,option_2,option_3,option_4,correct_answer,explanation,difficulty,category,subcategory1,subcategory2

2行目以降が1問です。カンマや改行をフィールドに入れるときは、そのフィールド全体をダブルクォートで囲みます。フィールドの中の " は "" と二つ書きます。

question_text

問題文です。空にはできません。語彙なら例文ごと入れた方が、単語だけの暗記より後で使えます。同梱の「TOEIC 700 英日意味」も、単語単体ではなく文の中の語を聞いています。

question_type

次の三つのいずれかを英字で書きます。

• multiple_choice は四択です。
• true_false は正誤です。
• text_input は記述です。

省略できます。option_1 から option_4 のどれかに文字があれば四択、全部空なら記述、とみなします。正誤は選択肢が空でも true_false と明示してください。省略すると記述扱いになり、true / false の採点が意図とずれます。

option_1 から option_4

四択のとき、各列に選択肢を一つずつ書きます。使わない列は空で構いません。正誤と記述では四列とも空でよいです。

correct_answer

四択では正解の番号です。option_1 が正解なら 1、option_2 なら 2、以下同様に 4 までです。A や選択肢の文言ではなく、番号にしてください。正誤では true または false です。小文字を推奨します。記述では、正解の文字列そのものです。表記が複数あるときは / で区切れます。たとえば 東京/とうきょう のようにします。

explanation

その問いに対する解説です。正解の文言を繰り返すだけでは、あとで読み返したときに理由が残りません。「なぜその訳か」「どの語と紛らわしいか」を一文で書いてください。公開サンプルも、この列をページの本文にしています。

difficulty

0.0 から 1.0 の数値です。0.1 から 0.3 を基礎、0.4 から 0.6 を中級、0.7 から 1.0 を上級の目安にしています。範囲の外は拒否されることがあります。一つのファイルの中で難易度をばらけさせると、連続して同じ手応えになりにくいです。

category、subcategory1、subcategory2

自分で付ける分類です。空でも取り込めます。同梱セットでは TOEIC や 句動詞 B1 のように、後から絞れる名前を入れています。

行の例

四択の1行は、意味としては次の並びです。問題文、multiple_choice、選択肢四つ、正解番号、解説、難易度、分類。正誤の行は選択肢を空にし、question_type に true_false、correct_answer に true か false を書きます。記述の行は選択肢を空にし、correct_answer に語句を書きます。

JSON

ルートは一つのオブジェクトか、問題オブジェクトの配列です。オブジェクトにするときは title、description、questions を持たせます。任意で author、license、copyright（別名 copyright_notice）を付けられます。license が MIT のとき、画面の説明を開くとライセンス本文も出ます。

各問題の必須は question_text（別名 question）と correct_answer（別名 answer）です。任意は question_type、options（または option_1 から option_4）、explanation、difficulty、category、subcategory1、subcategory2 です。四択の correct_answer は、CSV と同じ番号のほか、A から D、または選択肢の文言でも受け取れます。difficulty は 0.0 から 1.0 です。

{
  "title": "日本の地理",
  "description": "記述・四択・正誤の例",
  "author": "Ultra Practicebook",
  "license": "MIT",
  "copyright": "Copyright (c) Ultra Practicebook",
  "questions": [
    {
      "question_text": "日本の首都は？",
      "question_type": "text_input",
      "correct_answer": "東京",
      "explanation": "日本の首都は東京都です",
      "difficulty": 0.2,
      "category": "地理"
    }
  ]
}

トップの JSON 取込、お試し作成の JSON タブ、ログイン後の問題集への追加は、この形を共通で使います。ログイン後に既存の問題集へ足す API は POST /questions/bulk-upload-json/{question_set_id} です。

取り込んだあとの確認

件数だけ見て終わらせないでください。先頭の三問を実際に解き、正解番号が選択肢とずれていないか、記述の / 区切りが一つの答えとして通るかを見ます。分類名が空のまま大量に入っていると、あとから弱い分野を探せません。直すときは元の CSV を修正して、取り込むセットを作り直す方が、画面で一問ずつ追うより確実です。

形式が壊れているファイルは、行番号が分かるエラーを出します。その行のクォートが閉じていないことが、ほとんどです。