The domcq/1 question file

A domcq/1 file is one set of multiple-choice questions as plain JSON: for each question its text, its options, the correct answer, an explanation and a topic, plus a few optional fields. It holds questions and nothing else: no scores, no sessions, no settings.

Your AI writes the file when you run a DoMcq prompt, whether it is writing new questions or copying yours from a document. DoMcq checks the file, imports it as written, and gives it back the same way when you export. One file is one set, of up to 500 questions.

An example file

These three questions are the only example questions on domcq.com. They are about the format itself, so they belong to no subject and no exam. The first has one correct answer, the second two, and the third has per-option rationales and a source.

To see the check pass, copy the file and paste it at domcq.com/import (signed in).

{
  "format": "domcq/1",
  "set": "Example: the domcq/1 format",
  "questions": [
    {
      "stem": "Which field of a domcq/1 question says which option is correct?",
      "options": [
        "stem",
        "answer",
        "topic",
        "source"
      ],
      "answer": "B",
      "explanation": "The answer field holds the letter of the correct option, counted by position: A is the first option, B the second.",
      "topic": "Fields",
      "difficulty": "easy"
    },
    {
      "stem": "Which of these fields must every domcq/1 question have? Choose TWO.",
      "options": [
        "explanation",
        "difficulty",
        "topic",
        "source"
      ],
      "answer": "AC",
      "explanation": "Every question needs a stem, options, an answer, an explanation and a topic. Difficulty and source are optional.",
      "topic": "Fields",
      "difficulty": "medium"
    },
    {
      "stem": "What is the largest number of options a domcq/1 question may have?",
      "options": [
        "Four",
        "Five",
        "Six",
        "Eight"
      ],
      "answer": "C",
      "explanation": "A question has between two and six options. An exam module can narrow that range but never widen it.",
      "rationales": {
        "A": "Four is a common number, but the format allows more.",
        "B": "Five is allowed, but it is not the most.",
        "C": "Six is the most: options are lettered A to F.",
        "D": "Eight is more than the format allows; the letters stop at F."
      },
      "topic": "Limits",
      "source": "domcq/1 specification, section 2"
    }
  ]
}

The fields

Lengths count characters after any spaces at either end are removed. No other field is allowed, at the top or in a question: a file with an extra field is refused, so nothing in it is silently lost.

The file

Field	Required	Rule
`format`	Yes	Exactly `"domcq/1"`.
`exam`	No	The id of a DoMcq exam module, or of your own exam profile; the prompt page writes it into the prompt for you. Without it, the Generic rules apply: any topic names and 2–6 options. An id DoMcq does not know is refused.
`set`	Yes	The set’s name, 1–120 characters.
`questions`	Yes	The questions, 1–500 per file.
`exported_at`	No	When the file was exported. DoMcq’s export writes it; leave it out otherwise.

Each question

Field	Required	Rule
`stem`	Yes	The question, including any case or scenario: 10–2000 characters.
`options`	Yes	2–6 options, each 1–500 characters, all different. An exam module may allow a narrower range.
`answer`	Yes	The correct option’s letter by position (`A` is the first option), or several capital letters in order, such as `"BD"`; never every option. An exam module may allow only one letter.
`explanation`	Yes	Why the answer is correct: 1–3000 characters.
`rationales`	No	Why each option is right or wrong, keyed by letter, for any of the question’s letters: `{"A": "…", "C": "…"}`, each 1–1000 characters. Shown under the options in tutor mode.
`topic`	Yes	1–80 characters. For an exam module, one of its official topics as its module page names them; otherwise any name, spelled the same way every time.
`subtopic`	No	1–120 characters.
`difficulty`	No	`easy`, `medium` or `hard`.
`source`	No	A reference you can check in your own materials: 1–200 characters.
`id`	No	1–64 characters: letters, digits and `_ - . :`, unique in the file. DoMcq’s export writes it so that importing the file again finds the same question; a prompt never asks for it.

How DoMcq checks a file

Paste the file at domcq.com/import, on the page called Import questions. “DoMcq checks it in your browser.” The check is strict and the same every time: it never guesses, repairs or rewrites anything.

Once the file is valid JSON, every problem is listed at once, problems with the file as a whole first, then by question number, so one reply from your AI can fix them all. Each message is written to be pasted back to the AI that wrote the file, for example “Question 2: `explanation` is missing but must be a string of 1–3000 characters explaining why the correct answer is correct.” Under Ask your AI to fix it, Copy fix request copies every message with a request for the complete corrected file.

Two things are notes, not problems: a question that is already in your account (skipped unless you choose to keep it), and a subtopic an exam module does not list (kept as written). Neither stops an import, unless every question in the file is already in your account.

The same check runs again on DoMcq’s server when you press Save, and on any question you edit from a results page.

An open format

Any tool may read and write domcq/1 files. The specification, the JSON Schema and the reference validator are published under the MIT license: github.com/kamranrashid-com/domcq-format. The JSON Schema is also at domcq.com/schema/v1.

Guides to using DoMcq