Schema Reference

Schema Reference

The DQ QuestionBank Core uses a versioned JSON Schema (v1.0) as its canonical interchange format.

Normative schema

The authoritative JSON Schema is at:

schema/question-set.schema.json

It is installed with the package and accessible via dq_questionbank.load_schema().

Top-level structure

{
  "schema_version": "1.0",
  "id": "set-001",
  "title": "My Question Set",
  "description": "Optional description",
  "language": "en",
  "questions": [ ... ],
  "metadata": {}
}

Question types

Type	Description
single_choice	Exactly one correct choice
multiple_choice	One or more correct choices
true_false	Binary true/false
fill_blank	Cloze or completion
short_answer	Free-text short response
essay	Extended written response
composite	Parent question with subquestions

Content blocks

Every stem, solution, hint, and choice.content is a Content object containing blocks:

Block type	Key fields
text	text
math	latex (inline or display)
image	asset_id, alt_text
table	rows (array of arrays)
code	text, language
line_break	(no fields)

Minimal valid question

{
  "schema_version": "1.0",
  "id": "q1",
  "type": "short_answer",
  "language": "en",
  "stem": {
    "blocks": [{ "type": "text", "text": "What is 2 + 2?" }]
  }
}

Asset safety

Asset URIs are validated:

• Allowed: relative paths, https:// URLs, data: URIs
• Rejected: absolute filesystem paths, .. traversal

SHA-256 integrity hashes are optional but recommended.

See also: question-schema.md in the repository.