Enabling New Question Types in Sunbird inQuiry (FTB, MTF, Sequence, Reorder)

Table of Contents

1. Introduction

2. Background

3. Problem Statement

4. Current State Baseline

5. Design Goals & Constraints

6. Design Decisions

7. Schema Changes

8. Type Registration

9. API Payload Contracts

10. Read API Behaviour — Language Filtering

11. Validation Rules

12. Scoring — Response Processing

13. Rollout & Compatibility

14. Open Items

Introduction

Sunbird inQuiry has implemented the QuML (Question Markup Language) specification across Assessment APIs, Editor, and Player. Two question types are enabled end-to-end today: Multiple Choice Question (MCQ) and Subjective Question (SA), both supporting multi-language (i18n) data at qumlVersion 1.1 per the existing "Multi-language support for Questions & QuestionSets" design.

Adopters have requested four additional QuML types: Fill in the Blanks (FTB), Match The Following (MTF), Sequence, and Reorder. Because these are being introduced after qumlVersion 1.1 and i18n already exist, they must comply with both from day one. This document covers the API-layer design only; Editor and Player changes are out of scope.

Terminology. "v4/v5 API" refers to the HTTP route version (/question/v4/, /question/v5/). "qumlVersion 1.1" refers to the data format version stored inside each question object. These are independent axes — new types use existing v4/v5 routes with qumlVersion: 1.1 payloads.

Background

The four new question types are being enabled in line with the QuML specification, which already defines them via the text, match, and order interactions. inQuiry is adopting these spec-defined interactions rather than inventing local equivalents, so questions authored in inQuiry remain interoperable with any spec-conformant tooling.

The work builds on the existing qumlVersion 1.1 schema — the same schema that already powers MCQ and SA with i18n support. No new schema version is being introduced. The 1.1 schema is extended in-place with additive changes (new enum values for interactionTypes, qType, cardinality, type, and scoringMode, plus a typed shape for the interactions block) so that the new types share the same authoring contract, the same i18n behaviour, and the same read/scoring pipeline as the types already in production.

In short: same schema version, additive updates, spec-aligned interactions.

Problem Statement

The current Assessment API supports only MCQ and SA. The QuML 1.1 schema, the per-category Object Category Definitions, and the validator layer recognise only the choice and text interaction types. As a result:

• Adopters needing FTB, MTF, Sequence, or Reorder are forced to model them as MCQs or build out-of-band solutions, breaking standardisation.

• The QuML specification already defines these types via the text, match, and order interactions — but the implementation does not validate or accept them.

• Without a defined response and scoring contract per type, downstream consumers (Player, scoring engine, telemetry) have no consistent shape to rely on.

• The new types must co-exist with the existing qumlVersion 1.1 / i18n contract — payloads, read transformations, lang= filtering, and v1.0→1.1 auto-migration must behave identically across all question types.

Current State Baseline

What is already in place

What QuML spec defines for the new interaction types

This table is the authoritative source for cardinality and type per interaction; it is referenced throughout the rest of this document rather than restated.

Key spec finding: map is a type value, not a cardinality value. The QuML cardinality enum is [single, multiple, ordered]. MTF uses cardinality: single with type: map. This shapes the schema changes in §6.

Design Goals & Constraints

• No new HTTP routes. All four new types use existing POST /question/v4/create, PATCH /question/v4/update/:id, and related v4/v5 endpoints.

• qumlVersion 1.1 only. New types do not exist at qumlVersion 1.0. The v1.0 path is frozen.

• Additive schema changes only. No existing enum values, field names, or required fields are removed or renamed.

• i18n parity with MCQ/SA. Every user-facing textual field — including interaction option labels — must accept both plain string and i18n map format, identical to MCQ and SA today.

• Language-neutral scoring. Scoring operates on option values (identifiers), never on labels. The exception is FTB, where the learner submits free text — correct answers must therefore be listed per language in mapping[].

• QuML spec alignment for scoringMode. Adopt the spec-correct value responseProcessing; retain the existing non-spec values (system, none) for backward compatibility.

Design Decisions

The key design choices and their rationale:

Schema Changes

All changes are additive enum extensions plus one shape formalisation for the interactions block. Files: schemas/question/1.1/schema.json and test_schema/question/1.1/schema.json (both must be updated in lockstep), plus one change in schemas/questionset/1.1/schema.json.

Notes on individual changes

• #1–#2 — match and order correspond to the spec HTML data attributes data-match-interaction and data-ordered-interaction. MTF is already in the qType enum and must not be re-added.

• #4 — correctResponse.value and mapping[].value already accept object and array types in the current schema, so MTF (object value) and Sequence/Reorder (array value) require no change to those fields.

• #5 — responseProcessing is the QuML spec-correct value for questions with built-in scoring. Old values are retained so existing live questions remain valid; no data migration is required.

• #6 — The interactions field is currently an untyped object. The formalised shape enforces:

  • type is one of the known interaction-type values.

  • For order: options is a flat array of option objects.

  • For match: options is an object with left and right arrays of option objects.

  • Each option object has value (string; language-neutral identifier), label (plain string OR i18n map), and optional hint (same shape as label).

  This interactionOption shape is the same rule already applied to MCQ option labels, now extended uniformly.

Known divergences not being fixed. mapping[].key/value in the QuML spec are named value/score in the local schema. feedback and hints are keyed objects locally vs. arrays of {id, body} in the spec. These are documented intentional divergences and are out of scope for this release.

Type Registration

Two things must be registered for each new type:

1. Master category — visible string used in primaryCategory. Append to scripts/definition-scripts/master_category_create. Endpoint: POST /object/category/v4/create.

2. Object Category Definition — per-type schema constraints applied at create/update. Endpoint: POST /object/category/definition/v4/create.

The FTB Question master category already exists; only the three new ones below need registering. The FTB definition script does exist but has an empty schema and must be filled in.

Each definition constrains interactionTypes, mimeType (always application/vnd.sunbird.question), primaryCategory (the display name), and qType.

Example — MTF definition (pattern applies to all four):

For FTB, Sequence, and Reorder, substitute the corresponding categoryId, interactionTypes, primaryCategory, and qType from the table above.

API Payload Contracts

Common conventions

These conventions apply uniformly to all four new types. Per-type sections below show only what differs.

• Endpoints. All four types use the existing routes:

  POST /question/v4/create (or /question/v5/create) PATCH /question/v4/update/:id (or /question/v5/update/:id) POST /question/v4/review/:id POST /question/v4/publish/:id POST /question/v4/copy/:id

• i18n shape. Every user-facing textual field — body, instructions, answer, hints, feedback, solutions, and every option label / hint — accepts either a plain string or an i18n map { "lang_code": "html" }. Plain strings are normalised to { "<systemDefaultLang>": "<value>" } at write time, so reads always return the map shape.

• value is language-neutral. Inside interactions.options, correctResponse, and mapping[], the value field is an identifier and is never i18n-keyed.

• mapping field naming. Sunbird uses value for the answer value and score for the score. The QuML base spec uses key and value respectively. This is a documented intentional divergence — integrators connecting raw spec-conformant players must map accordingly.

FTB — Fill in the Blanks

Rules.