YAML Question Schema

This document describes the complete YAML schema for multiple‑choice questions.

Top-Level Structure

A question file contains one top‑level key:

questions:
  - <question>
  - <question>
  ...

Question Structure

Each question is a mapping with the following required fields:

id: <string>
topic: <string>
points: <integer>
type: mcq | tf
stem: <list of stem blocks>
choices: <list of 4 choices if mcq>
correct: <a/b/c/d/true/false>
explanation: <string>

mcq questions have four choices (a, b, c, d), while tf questions have two choices (true, false).

Stem Blocks

Each question must contain at least one stem block of type text. A stem block has:

- type: text | code
  text: <string>

Rules:

  • type: text blocks may contain inline code using double-backticks (like this).

  • type: code blocks contain literal Python code.

  • Printed output in code must not include quotes.

  • Any literal newline in quoted YAML strings must appear as \n.

  • Multi-line code is preferably written using YAML block scalars (|).

Acceptable stem shapes include:

  • text

  • text -> code

  • text -> code -> text

  • Multiple text blocks

Not allowed:

  • A stem consisting only of code blocks.

Choices

There must be exactly four choices, each with:

- key: a | b | c | d
  type: text | code
  text: <string>

Use type: code when the choice represents code or a Python literal, e.g.:

  • x = 2 + 3

  • 7

  • "hello"

  • x (identifier)

  • n % 10

Use type: text for prose answers.

Correct Answer and Explanation

  • correct must match one of: a, b, c, d, or true, false for a true-false.

  • explanation is required and may contain inline code markup (like this).

Output Formatting Rules

  • print("hello") → output is written as hello (no quotes).

  • Expression values show quotes only when the Python literal includes them.

  • Inline code only allowed in text blocks, never in code blocks.

Newline Rules

Inside quoted YAML scalars:

  • Literal newlines must be written as \n.

  • Use block scalars (|) for multi-line code when possible.

Summary of Constraints

  1. Every question has at least one type: text stem block.

  2. Code-only stems are forbidden.

  3. Choices must use correct type (text vs code).

  4. Inline code only in text blocks using double-backticks.

  5. Exactly four choices per question.

  6. Explanation required.

  7. Printed output must never include quotes.