Building Schema-Driven Quizzes with TypeScript & YAML: Introducing QMark

#typescript #node #webdev #opensource

Building quizzes, assessments, and questionnaires in code often involves writing repetitive UI state logic and rigid database schemas.

To solve this, I created QMark — an open-source schema parser and CLI ecosystem designed to make quiz creation as clean and portable as writing Markdown.

🛠️ The Problem

When building dynamic questionnaires, developers usually face two friction points:

Hardcoding quiz structures inside component state.
Manually writing custom exporters for rendering results into PDF, SVG, or Canvas outputs.

QMark decouples questionnaire structure from presentation using a declarative qmark-compose.yaml file.

🚀 How QMark Works

The QMark ecosystem consists of two core packages published under @silverio-labs:

@silverio-labs/qmark-core: A TypeScript core parser that processes and validates qmark-compose.yaml schemas.
@silverio-labs/qmark-cli: A command-line utility for schema validation, formatting, and rendering.

💻 Quick Start & Code Example

1. Install Core Parser

npm install @silverio-labs/qmark-core

2. Define a qmark-compose.yaml Schema

version: "1.0"
quiz:
  title: "TypeScript Fundamentals Assessment"
  questions:
    - id: "q1"
      type: "single-choice"
      prompt: "What is the return type of a function that never returns?"
      options:
        - label: "void"
          correct: false
        - label: "never"
          correct: true
        - label: "unknown"
          correct: false

3. Parse Schema in TypeScript

import { parseQMarkSchema } from '@silverio-labs/qmark-core';
import fs from 'fs';

const yamlContent = fs.readFileSync('qmark-compose.yaml', 'utf-8');
const parsedQuiz = parseQMarkSchema(yamlContent);

console.log(`Loaded Quiz: ${parsedQuiz.title}`);

🎨 Command Line Interface (CLI) & Exports

With @silverio-labs/qmark-cli, you can validate schemas and render outputs directly from your terminal or build scripts:

# Validate your schema
npx @silverio-labs/qmark-cli validate qmark-compose.yaml

# Render to SVG or HTML5 Canvas export
npx @silverio-labs/qmark-cli render qmark-compose.yaml --format svg --out quiz-preview.svg

Try It Out & Get Involved
Playground: https://silverio-labs.com/qmark/playground

npm Packages:
@silverio-labs/qmark-core | @silverio-labs/qmark-cli

I'd love to hear your feedback! Have you built schema-driven tools before? What rendering targets would you like to see next?

DEV Community