Format Guide

Format Guide

DQ QuestionBank Core supports four import/export formats:

JSON

• Extensions: .json
• Round-trip: canonical and deterministic
• Use for: storage, API integration, canonical interchange

dq import questions.json -o questions.json
dq convert questions.md --output-format json -o output.json

Markdown

• Extensions: .md, .markdown
• Round-trip: canonical for generated files
• Use for: human-readable archives, documentation, git-friendly diffs

Generated Markdown includes machine-readable markers (<!-- dq:question {...} -->) that enable deterministic re-import. Hand-written Markdown can also be imported with basic formatting.

dq convert questions.json --output-format markdown -o questions.md
dq import questions.md -o questions.json

LaTeX

• Extensions: .tex
• Round-trip: canonical for generated files; basic enumerate fallback for simple documents
• Use for: academic paper integration, printable question sheets

Generated LaTeX documents include JSON markers in comments for deterministic import. Simple \begin{enumerate} ... \item documents can be imported as a best-effort fallback.

dq convert questions.json --output-format latex -o questions.tex

DOCX

• Extensions: .docx
• Round-trip: core fields only; formatting is best-effort
• Use for: Microsoft Word workflows, teacher handouts

DOCX uses a visible-label convention: question type, language, choices, answers, and solutions are written as labeled paragraphs. Embedded images are extracted to a sidecar directory with SHA-256 hashing.

dq import exam.docx -o questions.json --assets-dir extracted_images
dq convert questions.json --output-format docx -o output.docx --assets-base ./images

DOCX support requires the optional python-docx dependency.

Comparison

Feature	JSON	Markdown	LaTeX	DOCX
Round-trip	Full	Full	Full (generated)	Core fields
Images	Asset refs	Asset refs	Placeholder	Embedded extraction
Math	LaTeX in block	LaTeX inline/display	Native	$-delimited
Human readability	Low	High	Medium	High

See also: compatibility.md