Categories

Overview

Categories provide a powerful way to organize questions into logical groups within your knowledge checks. They enable you to structure content hierarchically, create prerequisite relationships, and track performance across different topic areas.

Every question in a knowledge check must be assigned to a category. By default, questions belong to the ‘general’ category.

Category Structure

Each category is defined with the following properties:

{
  id: string,                        // Unique identifier (UUID)
  name: string,                      // Category name (must be unique)
  prequisiteCategoryId: string | null,  // ID of required category
  skipOnMissingPrequisite: boolean    // Behavior when prerequisite not met
}

Category Properties

A unique UUID automatically generated for each category.

id: string // UUID format

Used internally to reference categories and establish relationships.

Name

A human-readable identifier for the category.

name: string // e.g., 'javascript-basics', 'advanced-concepts'

Must be unique within the knowledge check
Used when assigning questions to categories
Displayed to users during assessments
Shown in performance breakdowns

Choose clear, descriptive names that help users understand the topic area. Use lowercase with hyphens for consistency.

Prerequisite Category ID

Specifies another category that must be completed first.

prequisiteCategoryId: string | null

Set to null for no prerequisite (default)
Set to another category’s ID to create a dependency
Enables progressive learning paths
Enforces skill progression

Example:

{
  "name": "advanced-javascript",
  "prequisiteCategoryId": "<id-of-javascript-basics>"
}

Users must complete “javascript-basics” before accessing “advanced-javascript” questions.

Skip on Missing Prerequisite

Controls behavior when a prerequisite is not met.

skipOnMissingPrequisite: boolean // Default: false

false (default)
true

Strict enforcement: Questions from this category are hidden/locked until the prerequisite is satisfied.

{
  "name": "advanced-concepts",
  "prequisiteCategoryId": "<basics-id>",
  "skipOnMissingPrequisite": false
}

Users cannot access these questions until they complete the prerequisite category.Use when:

Prerequisites are essential for understanding
You want to enforce learning order
Content builds strictly on previous knowledge

Soft recommendation: Questions are available but marked as advanced/recommended after prerequisite.

{
  "name": "bonus-topics",
  "prequisiteCategoryId": "<core-topics-id>",
  "skipOnMissingPrequisite": true
}

Users can access these questions immediately but are informed about the recommended order.Use when:

Prerequisites are recommended but not required
Users may have prior knowledge
Flexible learning paths are desired

Creating Categories

Categories are defined in the knowledge check schema:

{
  "questionCategories": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "general",
      "prequisiteCategoryId": null,
      "skipOnMissingPrequisite": false
    }
  ]
}

Default Category

Every knowledge check starts with a default ‘general’ category:

{
  "questionCategories": [
    {
      "id": "<generated-uuid>",
      "name": "general",
      "prequisiteCategoryId": null,
      "skipOnMissingPrequisite": false
    }
  ]
}

The ‘general’ category is created automatically if no categories are specified. All questions default to this category unless explicitly assigned elsewhere.

Assigning Questions to Categories

Each question references a category by name:

{
  "questions": [
    {
      "id": "q1",
      "question": "What is a variable?",
      "category": "javascript-basics",
      "type": "single-choice",
      "points": 5,
      "accessibility": "all",
      "answers": [...]
    },
    {
      "id": "q2",
      "question": "Explain closures",
      "category": "advanced-javascript",
      "type": "open-question",
      "points": 20,
      "accessibility": "exam-only"
    }
  ]
}

All questions must reference existing categories. The system validates that each question’s category exists in the questionCategories array. Using a non-existent category will cause validation errors.

Category Hierarchies

Create learning progressions using prerequisite relationships:

Example: Programming Course

{
  "questionCategories": [
    {
      "id": "cat-1",
      "name": "programming-fundamentals",
      "prequisiteCategoryId": null,
      "skipOnMissingPrequisite": false
    },
    {
      "id": "cat-2",
      "name": "control-structures",
      "prequisiteCategoryId": "cat-1",
      "skipOnMissingPrequisite": false
    },
    {
      "id": "cat-3",
      "name": "functions-and-scope",
      "prequisiteCategoryId": "cat-2",
      "skipOnMissingPrequisite": false
    },
    {
      "id": "cat-4",
      "name": "object-oriented-programming",
      "prequisiteCategoryId": "cat-3",
      "skipOnMissingPrequisite": false
    },
    {
      "id": "cat-5",
      "name": "advanced-patterns",
      "prequisiteCategoryId": "cat-4",
      "skipOnMissingPrequisite": false
    }
  ]
}

Learning Path:

Programming Fundamentals (no prerequisite)
Control Structures (requires Fundamentals)
Functions and Scope (requires Control Structures)
Object-Oriented Programming (requires Functions)
Advanced Patterns (requires OOP)

Example: Flexible Certification

{
  "questionCategories": [
    {
      "id": "cat-1",
      "name": "core-concepts",
      "prequisiteCategoryId": null,
      "skipOnMissingPrequisite": false
    },
    {
      "id": "cat-2",
      "name": "intermediate-topics",
      "prequisiteCategoryId": "cat-1",
      "skipOnMissingPrequisite": false
    },
    {
      "id": "cat-3",
      "name": "specialization-a",
      "prequisiteCategoryId": "cat-2",
      "skipOnMissingPrequisite": true
    },
    {
      "id": "cat-4",
      "name": "specialization-b",
      "prequisiteCategoryId": "cat-2",
      "skipOnMissingPrequisite": true
    }
  ]
}

Learning Path:

Core Concepts (required start)
Intermediate Topics (must complete Core)
Choose either Specialization A or B (both available after Intermediate)

Using skipOnMissingPrequisite: true for specializations allows users to access them immediately, but the UI can show recommendations about completing the prerequisite first.

User Experience

How Users See Categories

Category Overview

When viewing a knowledge check, users see categories listed with:

Category name
Number of questions in each category
Lock status if prerequisites not met
Completion percentage (in practice mode)

During Assessment

While taking an exam or practicing:

Questions grouped or labeled by category
Progress tracked per category
Locked categories indicated with icon/message
Prerequisite requirements shown

Results Breakdown

After completion:

Score displayed per category
Performance comparison across categories
Identify strong and weak areas
Recommendations for improvement

Prerequisites in Action

Scenario: Strict Prerequisites

{
  "name": "advanced-topics",
  "prequisiteCategoryId": "<basics-id>",
  "skipOnMissingPrequisite": false
}

What users see:

“Advanced Topics” appears locked/grayed out
Message: “Complete ‘Basics’ to unlock this category”
Questions from this category are not displayed
Category unlocks automatically after prerequisite completion

Scenario: Recommended Prerequisites

{
  "name": "expert-level",
  "prequisiteCategoryId": "<intermediate-id>",
  "skipOnMissingPrequisite": true
}

What users see:

“Expert Level” is accessible immediately
Badge or icon: “Recommended after ‘Intermediate’”
Optional confirmation: “This content builds on Intermediate. Continue?”
Full access to all questions

Performance Tracking

Categories enable detailed performance analytics:

Individual Performance

{
  "categoryScores": [
    {
      "category": "javascript-basics",
      "score": 45,
      "maxScore": 50,
      "percentage": 90,
      "questionsAttempted": 10,
      "questionsCorrect": 9
    },
    {
      "category": "advanced-javascript",
      "score": 30,
      "maxScore": 60,
      "percentage": 50,
      "questionsAttempted": 12,
      "questionsCorrect": 6
    }
  ]
}

Users can see exactly which topics they’ve mastered and which need more study.

Aggregate Analytics

Category Difficulty: Average scores across all users per category
Drop-off Rates: Which categories have highest abandonment
Prerequisite Effectiveness: Do prerequisites improve advanced category performance?
Time per Category: How long users spend in each section

Best Practices

Organizing Content

Logical Grouping

Group related questions together:

By topic or concept
By skill level
By learning objective
By question type (if relevant)

Balanced Categories

Aim for even distribution:

5-15 questions per category
Similar difficulty within categories
Comparable time requirements
Consistent point values

Clear Naming

Use descriptive category names:

Lowercase with hyphens
Reflect actual content
Avoid abbreviations
Be specific and clear

Progressive Difficulty

Build prerequisite chains:

Start with fundamentals
Build to advanced topics
Create clear learning paths
Use appropriate prerequisite modes

When to Use Prerequisites

Strict Prerequisites
Soft Prerequisites
No Prerequisites

Use skipOnMissingPrequisite: false when:

Content requires prior knowledge to understand
Following a curriculum or course structure
Building skills sequentially
Preventing user frustration with too-advanced content
Ensuring proper learning progression

Examples:

Programming courses (basics before advanced)
Mathematics (algebra before calculus)
Language learning (beginner before intermediate)
Professional certifications with levels

Use skipOnMissingPrequisite: true when:

Prerequisites are helpful but not essential
Users may have prior external knowledge
Allowing flexible learning paths
Content is supplementary or enrichment
Different specializations from same base

Examples:

Optional advanced topics
Specialization tracks
Bonus or challenge content
Alternative approach to same concepts

Use prequisiteCategoryId: null when:

All categories are independent
Assessment tests broad knowledge
Questions can be answered in any order
No skill dependencies exist

Examples:

General knowledge quizzes
Mixed-topic assessments
Placement tests
Survey-style questions

Common Patterns

Pattern 1: Linear Progression

A → B → C → D

Each category requires the previous one. Creates a clear learning path. Pattern 2: Tree Structure

Core concepts branch into specializations. Pattern 3: Flat Organization

A   B   C   D

No prerequisites. All categories independent and accessible. Pattern 4: Hybrid Model

    A → B
    ↓   ↓
    C   D   E

Some prerequisites required, others optional or none.

Example Configurations

Example 1: Web Development Course

{
  "questionCategories": [
    {
      "id": "html-basics",
      "name": "html-fundamentals",
      "prequisiteCategoryId": null,
      "skipOnMissingPrequisite": false
    },
    {
      "id": "css-basics",
      "name": "css-fundamentals",
      "prequisiteCategoryId": null,
      "skipOnMissingPrequisite": false
    },
    {
      "id": "js-basics",
      "name": "javascript-fundamentals",
      "prequisiteCategoryId": null,
      "skipOnMissingPrequisite": false
    },
    {
      "id": "responsive",
      "name": "responsive-design",
      "prequisiteCategoryId": "css-basics",
      "skipOnMissingPrequisite": false
    },
    {
      "id": "frameworks",
      "name": "javascript-frameworks",
      "prequisiteCategoryId": "js-basics",
      "skipOnMissingPrequisite": false
    },
    {
      "id": "fullstack",
      "name": "full-stack-integration",
      "prequisiteCategoryId": "frameworks",
      "skipOnMissingPrequisite": true
    }
  ]
}

Example 2: Product Knowledge Assessment

{
  "questionCategories": [
    {
      "id": "cat-1",
      "name": "product-overview",
      "prequisiteCategoryId": null,
      "skipOnMissingPrequisite": false
    },
    {
      "id": "cat-2",
      "name": "features-and-benefits",
      "prequisiteCategoryId": null,
      "skipOnMissingPrequisite": false
    },
    {
      "id": "cat-3",
      "name": "pricing-and-packages",
      "prequisiteCategoryId": null,
      "skipOnMissingPrequisite": false
    },
    {
      "id": "cat-4",
      "name": "competitive-comparison",
      "prequisiteCategoryId": null,
      "skipOnMissingPrequisite": false
    },
    {
      "id": "cat-5",
      "name": "sales-scenarios",
      "prequisiteCategoryId": null,
      "skipOnMissingPrequisite": false
    }
  ]
}

No prerequisites - all categories independent and can be completed in any order.

Validation Rules

KnowledgeCheckr enforces strict validation to maintain data integrity:

Category Name Uniqueness: No two categories can have the same name
Valid Question References: All questions must reference existing categories
Valid Prerequisite IDs: prequisiteCategoryId must reference an existing category or be null
No Circular Dependencies: Prerequisites cannot create circular references (A → B → A)
ID Format: Category IDs must be valid UUIDs

Troubleshooting

Questions Not Appearing

Issue: Questions assigned to a category aren’t showing up.Check:

Category name in question matches exactly (case-sensitive)
Category exists in questionCategories array
No typos in category name
Question accessibility setting allows it in current mode

Prerequisites Not Working

Issue: Users can access categories they shouldn’t.Check:

prequisiteCategoryId is set correctly
skipOnMissingPrequisite is false for strict enforcement
Prerequisite category ID exists and is correct
User has actually completed prerequisite (check completion logic)

Validation Errors

Issue: Knowledge check won’t save due to category errors.Check:

All category names are unique
All questions reference existing categories
No circular prerequisite dependencies
All IDs are valid UUIDs
Required fields (id, name) are present

Next Steps

Question Types

Learn about assigning questions to categories

Practice Mode

See how categories affect practice sessions

Examination Mode

Understand category performance in exams

Knowledge Checks

Back to knowledge check overview

Getting Started

Core Features

User Guide

Configuration

Overview

Category Structure

Category Properties

Creating Categories

Default Category

Assigning Questions to Categories

Category Hierarchies

Example: Programming Course

Example: Flexible Certification

User Experience

How Users See Categories

Prerequisites in Action

Performance Tracking

Individual Performance

Aggregate Analytics

Best Practices

Organizing Content

Logical Grouping

Balanced Categories

Clear Naming

Progressive Difficulty

When to Use Prerequisites

Common Patterns

Example Configurations

Example 1: Web Development Course

Example 2: Product Knowledge Assessment

Validation Rules

Troubleshooting

Next Steps

Question Types

Practice Mode

Examination Mode

Knowledge Checks

Build docs developers (and LLMs) love

Getting Started

Core Features

User Guide

Configuration

​Overview

​Category Structure

​Category Properties

​Creating Categories

​Default Category

​Assigning Questions to Categories

​Category Hierarchies

​Example: Programming Course

​Example: Flexible Certification

​User Experience

​How Users See Categories

​Prerequisites in Action

​Performance Tracking

​Individual Performance

​Aggregate Analytics

​Best Practices

​Organizing Content

Logical Grouping

Balanced Categories

Clear Naming

Progressive Difficulty

​When to Use Prerequisites

​Common Patterns

​Example Configurations

​Example 1: Web Development Course

​Example 2: Product Knowledge Assessment

​Validation Rules

​Troubleshooting

​Next Steps

Question Types

Practice Mode

Examination Mode

Knowledge Checks

Build docs developers (and LLMs) love

Overview

Category Structure

Category Properties

Creating Categories

Default Category

Assigning Questions to Categories

Category Hierarchies

Example: Programming Course

Example: Flexible Certification

User Experience

How Users See Categories

Prerequisites in Action

Performance Tracking

Individual Performance

Aggregate Analytics

Best Practices

Organizing Content

When to Use Prerequisites

Common Patterns

Example Configurations

Example 1: Web Development Course

Example 2: Product Knowledge Assessment

Validation Rules

Troubleshooting

Next Steps