QTI ↔ Learnosity Converter

A TypeScript tool for converting between QTI (Question & Test Interoperability) and Learnosity JSON formats. Use it as a CLI tool on the command line, or as a library imported into your own Node.js project.

Documentation

• Getting Started - Installation, quick start (CLI and library), and basic workflow
• QTI Structure - Support for QTI structural elements (assessmentItem, assessmentTest, assessmentSection, testPart)
• Diagnostics - Understanding diagnostic messages and the diagnostics file
• Supported Interactions - Complete list of QTI ↔ Learnosity mappings
• Learnosity Bundle Format - Expected input format for Learnosity → QTI conversion
• Learnosity Sections - How Learnosity activity sections map to QTI assessmentTest structure
• Examples - CLI and programmatic usage examples
• FAQ - Troubleshooting and common questions

Prerequisites

• Node.js >= 22.0.0

Installation

npm install @learnosity/lib-qti-converter

This single install gives you both the CLI tool and the importable library. All dependencies are bundled — there's nothing else to install.

For Contributors (from source)

git clone <repository-url>
cd lib-qti-converter
pnpm install
pnpm run build

Quick Start

CLI Usage

# Install globally for CLI access
npm install -g @learnosity/lib-qti-converter

# Convert QTI to Learnosity
lcon qti-to-learnosity --in item.xml --out item.json --pretty

# Convert Learnosity to QTI
lcon learnosity-to-qti --in item.json --out item.xml

Library Usage

import { convertQtiToLearnosity } from '@learnosity/lib-qti-converter';

const result = await convertQtiToLearnosity(qtiXmlString, {
    qtiVersion: '2.2',
    outputFormat: 'dir',
    diagnostics: 'none',
    verbose: false,
    pretty: true,
});

console.log(result.output); // Converted Learnosity JSON
console.log(result.diagnostics); // Array of diagnostic messages

See Getting Started for detailed instructions and Examples for more usage scenarios.

Available Commands (CLI)

The CLI provides four main conversion commands:

• qti-to-learnosity - Convert QTI XML to Learnosity JSON
• qti-package-to-learnosity - Convert QTI Content Package to Learnosity bundle
• learnosity-to-qti - Convert Learnosity JSON to QTI XML
• learnosity-to-qti-package - Convert Learnosity bundle to QTI Content Package

Batch Processing: The package conversion commands (qti-package-to-learnosity and learnosity-to-qti-package) support a --recursive flag to convert multiple packages in subdirectories with a single command. See Examples - Batch Processing for details.

Run lcon <command> --help for detailed options, or see Examples for usage scenarios.

QTI Validation (not bundled)

After converting Learnosity to QTI, you can validate the generated QTI XML against the official IMS XSD schemas:

# Validate all QTI XML files in a directory
npm run validate:qti output/qti/

# Validate a specific file
npm run validate:qti output/qti/item.xml

# Debug mode to see schema resolution details
npm run validate:qti:debug output/qti/

Note: the validation script requires Python and lxml library to be installed.

npm run setup:python
npm run validate:qti output/qti/

Features:

• Uses local XSD schemas (not remote) via XML catalog
• Automatically detects file types and uses appropriate schemas:
  • QTI items/tests → QTI 2.2 schema (imsqti_v2p2p4.xsd)
  • Manifest files → IMS Content Packaging v1.1.4 schema (imscp_v1p1.xsd)
  • LOM metadata → IMS Learning Resource Metadata v1.2.4 schema (imsmd_v1p2p4.xsd)

Schema Versions:

When generating QTI Content Packages, we use the following IMS specifications:

| Component | Specification | Version | Schema File | | ---------------- | ------------------------------------ | ----------- | ------------------- | | QTI Items/Tests | IMS Question & Test Interoperability | 2.2 Patch 4 | imsqti_v2p2p4.xsd | | Package Manifest | IMS Content Packaging | 1.1.4 | imscp_v1p1.xsd | | LOM Metadata | IMS Learning Resource Metadata | 1.2.4 | imsmd_v1p2p4.xsd |

All schemas are stored locally in ./schemas/qti/ and resolved via the XML catalog (./schemas/catalog.xml).

Requirements:

• Python 3
• lxml library: pip install lxml

Example output:

⠋ Validated: 45/100 files...
---- invalid-item.xml ----
invalid-item.xml:12: Element 'choiceInteraction': Missing required attribute 'responseIdentifier'.
invalid-item.xml:15: Element 'simpleChoice': Missing required attribute 'identifier'.

Validated: 100/100 files - Complete!

Summary:
  Total files:    102
  Valid:          100
  Failed:         2

By folder:
  items/          98/100
  metadata/       100/100
  tests/          1/1
  imsmanifest.xml 1/1

Note: This is a development/testing tool for validating QTI output. It's not required for normal conversion operations.

Learnosity JSON Validation

After converting QTI to Learnosity (or to validate existing Learnosity JSON files), you can validate the Learnosity JSON structure:

# Validate all Learnosity JSON files in items/ and activities/ subdirectories
npm run validate:learnosity output/learnosity/

# Validate all JSON files recursively in a directory
npm run validate:learnosity output/learnosity/ --recursive

# Validate a specific file
npm run validate:learnosity output/learnosity/items/item.json

Note: When validating a directory without --recursive, the script only looks in ./items and ./activities subdirectories. Use --recursive to validate all JSON files in the directory tree.

Features:

• Validates item structure (required fields, widget references)
• Validates question types (mcq, clozetext, shorttext, longtextV2, etc.)
• Validates validation objects (valid_response, alt_responses)
• Checks data type correctness for each question type:
  • MCQ: valid_response.value must be array of strings
  • Clozetext: valid_response.value must be array (one per gap)
  • Shorttext: valid_response.value can be string or array (synonyms)
• Validates HTML content in stimulus and template fields
• Provides clear error messages with diagnostic codes

Example output:

Validating Learnosity JSON files in: output/items/

packages/core/test/fixtures/learnosity/items/clozetext/no-placeholders.json:
  ❌ [ERROR] LRN_CLOZE_NO_PLACEHOLDERS: clozetext template must contain at least one {{response}} placeholder

packages/core/test/fixtures/learnosity/items/clozetext/len-mismatch.json:
  ❌ [ERROR] LRN_CLOZE_VALID_RESPONSE_LEN_MISMATCH: valid_response.value length (1) does not match placeholder count (2)

======================================================================
Validation Summary:
  Total files validated: 46
  Files with errors: 2
  Files with warnings: 0

❌ Validation failed with 2 error(s)
======================================================================

Use Cases:

• Quality assurance - Validate existing Learnosity JSON files
• Post-conversion testing - Verify converter output after code changes
• CI/CD integration - Automated validation with exit codes (0 = success, 1 = errors)

Note: This is a development/testing tool. It's not required for normal conversion operations but is useful for ensuring quality after code changes.

Development Scripts

pnpm run build                  # Compile TypeScript to JavaScript
pnpm run coverage:cli           # Run CLI tests with coverage
pnpm run coverage:core          # Run core tests with coverage
pnpm run lint                   # Check code quality
pnpm run lint:fix               # Auto-fix linting issues
pnpm run test                   # Run all tests (core + cli)
pnpm run test:cli               # Run CLI package tests only
pnpm run test:core              # Run core package tests only
pnpm run validate:learnosity    # Validate Learnosity JSON structure (see Learnosity JSON Validation section)
pnpm run validate:qti           # Validate QTI XML against XSD schema (see QTI Validation section)
pnpm run validate:qti:debug     # Validate QTI XML in debug mode

Local Development

# Install and build
pnpm install
pnpm run build

# Run the CLI
npm run lcon -- --help

Project Structure

This is a TypeScript monorepo using pnpm workspaces. Both packages are bundled into self-contained files using tsdown, so the published package has zero runtime dependencies.

lib-qti-converter/
├── packages/
│   ├── core/                   # @learnosity/converter-core - Conversion logic (the importable library)
│   └── cli/                    # @learnosity/converter-cli - Command-line interface
├── bin/                        # Utility scripts (validation tools)
│   ├── validateLearnosity.ts   # Learnosity JSON validation
│   └── validateQti.py          # QTI XML validation
├── schemas/                    # QTI/CC XSD schemas (2.1 and 2.2)
├── docs/                       # User documentation
│   ├── GETTING_STARTED.md
│   ├── EXAMPLES.md
│   └── FAQ.md
├── adr/                        # Architectural Decision Records
└── .github/prompts/            # AI-specific context and prompts

License

This project is licensed under the MIT License.