Citolab.QTI.Converter
0.2.5
dotnet add package Citolab.QTI.Converter --version 0.2.5
NuGet\Install-Package Citolab.QTI.Converter -Version 0.2.5
<PackageReference Include="Citolab.QTI.Converter" Version="0.2.5" />
<PackageVersion Include="Citolab.QTI.Converter" Version="0.2.5" />
<PackageReference Include="Citolab.QTI.Converter" />
paket add Citolab.QTI.Converter --version 0.2.5
#r "nuget: Citolab.QTI.Converter, 0.2.5"
#:package Citolab.QTI.Converter@0.2.5
#addin nuget:?package=Citolab.QTI.Converter&version=0.2.5
#tool nuget:?package=Citolab.QTI.Converter&version=0.2.5
Citolab.QTI.Converter and Citolab.QTI.Uploader
Small .NET library that:
- validates and extracts QTI package zip files
- optionally converts QTI 2.x packages to QTI 3 (via pluggable converter)
- streams the original zip and extracted entries to a consumer-provided callback (e.g. Blob Storage)
Packages / projects
Citolab.QTI.Uploader: core uploader abstractions + zip extractionCitolab.QTI.Converter: optional (pure .NET) converter implementation that converts QTI 2.x packages to QTI 3
NuGet publishing (GitHub Actions)
This repo includes a GitHub Actions workflow at .github/workflows/nuget.yml that builds/tests/packs on PRs and on pushes to main, and publishes to NuGet.org on:
- a tag push like
v0.1.0(uses the tag as the NuGet version), or - a manual run (Actions → workflow → Run workflow) with an optional
versioninput.
Publishing uses nuget.org Trusted Publishing: the workflow exchanges a GitHub OIDC token for an API key that is valid for one hour, so no API key is stored. To enable it:
- on nuget.org, under your username → Trusted Publishing, add a policy for repository owner
Citolab, repositoryqti-convert-dotnet, workflow filenuget.yml(no environment), owned by the account or organization that owns the packages; - add
NUGET_USERas a repository secret: the nuget.org profile name of that owner (not an email address).
Basic usage (ASP.NET Controller)
Create an IQtiPackageStore that uploads to your storage, then call QtiPackageUploader.UploadAsync(...).
QTI 2.x → QTI 3 conversion
If you want automatic conversion for QTI 2.x packages, configure QtiUploaderOptions:
using Citolab.QTI.Converter;
using Citolab.QTI.Uploader;
var uploader = new QtiPackageUploader();
var options = new QtiUploaderOptions
{
ConvertQti2ToQti3 = true,
Converter = new Qti2ToQti3PackageConverter(
new Qti2ToQti3PackageConverterOptions
{
ItemTransformOptions = new QtiItemTransformOptions
{
// These are enabled by default; set to false to disable.
ObjectToImg = true,
ObjectToVideo = true,
ObjectToAudio = true,
SsmlSubToSpan = true,
StripMaterialInfo = true,
MinChoicesToOne = true,
ExternalScored = true,
// Optional extras (off by default).
QbCleanup = false,
DepConvert = false,
UpgradePci = false,
StripStylesheets = false
},
// Optional per-item hook for consumer-specific transformations.
OnItemTransformedAsync = async (transform, itemPath, ct) =>
{
// Example: add a marker attribute
await transform.FnChAsync(doc =>
{
doc.Root?.SetAttributeValue("data-processed-by", "my-app");
return Task.CompletedTask;
});
}
})
};
The QTI 2.x → QTI 3 conversion is plain .NET (System.Xml.Linq, no XSLT processor or other dependencies) and behaves the same on net9.0 and netstandard2.0. It is a port of the qti2xTo30.xsl upgrader and is tested against that XSLT's recorded output.
QTI 3 → QTI 2.1 conversion
Qti3ToQti21PackageConverter converts a QTI 3 package back to QTI 2.1 (best-effort). Constructs without a QTI 2.1
equivalent are converted or removed and reported as warnings:
- shared stimuli are inlined into the items that reference them (and removed from the package and manifest)
- HTML5
audio/videobecomeobject, animgin graphic interactions becomes the requiredobject, and a gap text with only an image becomes agapImg - a PCI is wrapped in a
customInteraction;data-*,aria-*,role,dirand SSML are removed - HTML5-only elements (
section,figure,ruby, ...) becomediv/span - items that use QTI 3 shared vocabulary classes (
qti-layout-row,qti-underline, ...) get a stylesheet toqti3-shared-vocabulary.css, which is added next to the manifest and registered in it (InjectSharedVocabularyStylesheet, default on). It holds the 1EdTechqti3p0.cssutility classes, with its page-level layout section replaced by a grid sized by the row, plus fixes for QTI 2.1 players
using Citolab.QTI.Converter;
var converter = new Qti3ToQti21PackageConverter();
var result = await converter.ConvertQti3PackageToQti21Async("package.zip", cancellationToken); // writes package-qti21.zip
foreach (var warning in result.Warnings) Console.WriteLine(warning);
// or with streams
var warnings = await converter.ConvertAsync(inputStream, outputStream, cancellationToken);
// or a single file
var item = Qti3ToQti21XmlConverter.Convert(qti3Xml);
The item, test and manifest conversions can be replaced via Qti3ToQti21PackageConverterOptions
(ConvertItem, ConvertAssessment, ConvertManifest). The output is tested against the official QTI 2.1 XSD.
Item transformations
When converting an assessment item, the converter can apply a set of optional XML transformations via QtiTransform and QtiItemTransformOptions.
Default item transforms (enabled by default)
ObjectToImg: converts<object type="image/*" data="...">ALT</object>to<img src="..." alt="ALT" .../>.ObjectToVideo: converts<object type="video/*" ... data="...">to<video><source .../></video>and normalizes existing<video controls>usage.ObjectToAudio: converts<object type="audio/*" ... data="...">to<audio><source .../></audio>and normalizes existing<audio controls>usage.SsmlSubToSpan: converts SSML elements (e.g.<ssml:sub>,<ssml:break>,<ssml:say-as>, etc.) to<span>elements withdata-ssml-*attributes.StripMaterialInfo: removes<qti-companion-materials-info>.MinChoicesToOne: ensures<qti-choice-interaction min-choices>is at least1.ExternalScored: when there is no<qti-response-processing>, setsexternal-scored="human"on theSCOREoutcome declaration.
Additional item transforms (disabled by default)
QbCleanup: cleanup for common Question Builder (QB) HTML-ish wrappers (unwraps some<div>wrappers, span cleanup, etc.).DepConvert: converts Dutch Extension Profile dialog triggers (.dep-dialogTrigger) into HTMLpopoverbuttons.DepConvertExtended: converts DEP dialogs into a<dep-popup>structure (trigger + popup slot).HideInputsForChoiceInteractionWithImages: addsqti-input-control-hiddenwhen all choices contain images.UpgradePci: upgrades TAO-exported portable custom interactions into a structure expected by QTI components (moves properties todata-*, normalizes modules/markup, etc.).StripStylesheets: removes<qti-stylesheet>nodes; supports wildcard matching viaStripStylesheetsRemovePattern/StripStylesheetsKeepPattern.StylesheetsInlineAsync: fetches CSS content from external stylesheet URLs and inlines them into<qti-stylesheet>elements. Supports both HTTP URLs and relative file paths within QTI packages. UseOnItemTransformedAsynchook for custom async transformations like this.
Usage example for StylesheetsInlineAsync with ZIP uploads:
OnItemTransformedAsync = async (transform, itemPath, fileResolver, ct) =>
{
// Inline external stylesheets from ZIP package files
await transform.StylesheetsInlineAsync(async (resolvedPath, currentItemPath) =>
{
// resolvedPath is the stylesheet path resolved relative to the item
// Use the provided fileResolver to get CSS content from ZIP package
return await fileResolver(resolvedPath);
}, itemPath);
// Alternative: if stylesheets are HTTP URLs, use custom HTTP client
await transform.StylesheetsInlineAsync(async href => {
if (href.StartsWith("http"))
{
using var client = new HttpClient();
var response = await client.GetAsync(href, ct);
return response.IsSuccessStatusCode
? await response.Content.ReadAsStringAsync()
: null;
}
// For relative paths, use the ZIP file resolver
var resolvedPath = Path.Combine(Path.GetDirectoryName(itemPath) ?? "", href.Replace('/', Path.DirectorySeparatorChar));
return await fileResolver(resolvedPath.Replace('\\', '/'));
});
}
Example QTI Package Structure:
item1/
├── question.xml (contains <qti-stylesheet href="../shared/styles.css">)
└── item-specific.css
shared/
└── styles.css (CSS file to be inlined)
When processing item1/question.xml, the stylesheet ../shared/styles.css resolves to shared/styles.css in the ZIP package.
Consumer hook
Qti2ToQti3PackageConverterOptions.OnItemTransformedAsyncruns per assessment item after the built-in transforms, and receives a mutableQtiTransformso you can call.FnCh(...)/.FnChAsync(...)or chain additional built-ins.
License
GPL-3.0-only, see LICENSE. The QTI 2 → QTI 3 conversion is a port of the qti2xTo30.xsl upgrader by ETS (Apache-2.0); the shared vocabulary stylesheet contains the 1EdTech QTI 3 shared css utility classes.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
| .NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
| .NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
| .NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
| MonoAndroid | monoandroid was computed. |
| MonoMac | monomac was computed. |
| MonoTouch | monotouch was computed. |
| Tizen | tizen40 was computed. tizen60 was computed. |
| Xamarin.iOS | xamarinios was computed. |
| Xamarin.Mac | xamarinmac was computed. |
| Xamarin.TVOS | xamarintvos was computed. |
| Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Citolab.QTI.Uploader (>= 0.2.5)
-
net9.0
- Citolab.QTI.Uploader (>= 0.2.5)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.