[QTI] Carry legacy hints into generated QTI items as dormant catalog content

Overview

Legacy assessment items carry progressively-revealed hints (AssessmentItem.hints) that the QTI generator drops. Emit them into the generated QTI item as a qti-catalog-info catalog of support="ext:kolibri-hint" cards — dormant content the QTI 3.0 schema excludes from default delivery — carried in raw_data through publish so Kolibri can render them. Legacy-only; the new editor does not author hints.

Complexity: Medium
Target branch: unstable

Context

Legacy hints: AssessmentItem.hints is a JSON list [{"hint": <markdown>, "order": N}]; base.py:_process_hints converts markdown→HTML and extracts images.
The QTI generator (utils/assessment/qti/) emits nothing for hints today.
XSD validation ([QTI] QTI 3.0 schema XML validation utilities #6005) is authoritative and runs on save/publish.

The Change

Emit legacy hints into the generated QTI item as a dormant qti-catalog-info catalog — rendered by Kolibri, ignored by default players.

One qti-card support="ext:kolibri-hint" per hint, in display order; hint HTML inside qti-html-content.
id="kolibri-hints" — value not load-bearing; Kolibri selects on support.
Image refs emitted as standard src so the existing file scan ([QTI] Allow API endpoint to handle AssessmentItem.raw_data to store QTI data #5999) claims them.
No hints → no qti-catalog-info.

<qti-catalog-info>
  <qti-catalog id="kolibri-hints">
    <qti-card support="ext:kolibri-hint"><qti-html-content><p>First hint…</p></qti-html-content></qti-card>
    <qti-card support="ext:kolibri-hint"><qti-html-content><p>…solution.</p></qti-html-content></qti-card>
  </qti-catalog>
</qti-catalog-info>

Acceptance Criteria

A legacy item with hints generates a qti-catalog-info with one qti-card support="ext:kolibri-hint" per hint, in original order
Hint markdown is converted to HTML wrapped in qti-html-content
Hint images resolve as packaged files via the existing file scan ([QTI] Allow API endpoint to handle AssessmentItem.raw_data to store QTI data #5999)
An item with no hints generates no qti-catalog-info
Generated items validate against the QTI 3.0 XSD ([QTI] QTI 3.0 schema XML validation utilities #6005)
Tests cover multi-hint ordering, a hint with an image, and the no-hints case

References

QTI 3.0 qti-catalog-info (dormant catalog content): https://www.imsglobal.org/spec/qti/v3p0/impl

AI usage

Claude verified the carrier against the QTI 3.0 ASI XSD — confirming qti-catalog-info holds dormant, non-delivered content, accepts a custom ext:kolibri-hint support value, and that HTML <template> is restricted to custom-interaction markup — then drafted the issue section by section. The maintainer chose the catalog approach and the ext:kolibri-hint value and steered each section.

support="kolibri:hint" fails XSD validation.

The vendored XSD (imsqti_itemv3p0p1_v1p0.xsd) restricts CardDType/@support to a union of two options. Option 1 is a fixed enumeration (additional-directions, audio-description, braille, glossary-on-screen, high-contrast, keyboard-directions, keyword-translation, linguistic-guidance, long-description, sign-language, simplified-language-portions, simplified-graphics, spoken, tactile, transcript) — no hint value. Option 2 is SupportExtStringDType:

<xs:simpleType name="SupportExtStringDType">
    <xs:restriction base="xs:normalizedString">
        <xs:pattern value="(ext:)[a-zA-Z0-9_\.\-]+" />
    </xs:restriction>
</xs:simpleType>

This pattern requires the literal prefix ext:. No colon is allowed after it. kolibri:hint matches neither option, so a qti-card support="kolibri:hint" fails XSD validation — contradicting the acceptance criterion "Generated items validate against the QTI 3.0 XSD (#6005)".

Question: what exact support value should this use instead, e.g. ext:kolibri-hint?

The bot has been waiting for a response for 2 hour(s). It will resume automatically when someone replies.

Question: what exact support value should this use instead, e.g. ext:kolibri-hint?

Yes - I have updated the issue accordingly!

@rtibblesbot

Plan: Emit legacy AssessmentItem.hints into generated QTI items as a dormant qti-catalog-info catalog (support="ext:kolibri-hint" cards), carried through both the webapp publish path and the ricecooker ingest path, so Kolibri can render progressively-revealed hints that the QTI generator currently drops.

catalog.py — HtmlContent, Card, Catalog, CatalogInfo element classes
Wire catalog_info into AssessmentItem
_create_catalog_info in convert.py
Wire hints through archive.py (webapp publish path)
Wire hints through ingest.py (ricecooker ingest path)

@rtibblesbot's comments are generated by an LLM, and should be evaluated accordingly

How was this generated?

Implemented code following the pre-approved plan using test-driven development (red-green-refactor)
Ran the project's full test suite and linter before committing
For UI changes: captured live screenshots to verify rendering
For backend changes: verified with example API/CLI output

feat: derive structured Perseus data from a native QTI item

Navigation Menu

Repository navigation

[QTI] Carry legacy hints into generated QTI items as dormant catalog content #6011

Overview

Context

The Change

Acceptance Criteria

References

AI usage

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[QTI] Carry legacy hints into generated QTI items as dormant catalog content #6011

Description

Overview

Context

The Change

Acceptance Criteria

References

AI usage

Activity

rtibblesbot commented on Jul 8, 2026

rtibblesbot commented on Jul 8, 2026

rtibbles commented on Jul 8, 2026

rtibblesbot commented on Jul 9, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions