Wikisoba project/JSON specification for version 2

This page is kept as an archival reference.If you want to raise a point about it, please start a discussion thread on the community forum.

This is the working page for designing the JSON specification for Wikisoba Mark II.

Working assumptions

The JSON for any one "slide" (adopting the term in Mark I) reads as

{"configuration":configuration object, "meta":metadata object, "data":data array]

The configuration object includes giving the "slide type", which would be 1 for questions, out of about five types in all, the other types being ways of including supporting material. The object as explained below will have about a dozen fields.

The metadata should be adequate to the needs of Creative Commons licensing, at the very least. Who authored the question and licensing should be covered, and import, adaptation and authoring information maintained. A Wikidata item here to indicate general topic area would be a good idea. (Should look into general metadata use.) The legacy of Moodle export shows up in the JSON-GIFT sample, and is to reconcile with what we would want.

Overall structure of a quiz

This should be as:

{"intro": , "sections":section array, "outro": }

with the section array as:

[section(1), section(2), ..., section(K)]

and a section as

{"nav1": , "slides":slide array, "nav2": }

Here a slide array is like

[slide(1), slide(2), ..., slide(K)]

and the slides are expected to be of about five types, type #1 being the question type.

Choice-cloze type

This is a way of looking at some familiar types of question. There are is numerical parameter N. This is to be a versatile question type, including a number of typical multiple choice and missing text (cloze) formats.

In describing rendering, [(...)] means a rectangle, ((...)) means a rectangle with rounded corners.

Simple examples

First, the case N = 1.

A traditional choice question can be set up with

S(1) = "What is the capital of the USA?"
T(1) = {"true":"Washington DC", "dummy":{"false:"New York", "feedback":"New York is a large city in the USA, but not the capital."}}
S(2) = " "

This is to render as

What is the capital of the USA? [( )]

((New York)) ((Washington))

with the second line randomly ordered. If the incorrect answer "New York" is submitted, the message "New York is a large city in the USA, but not the capital." should appear in the feedback area.

The missing word option would read as

S(1) = "The capital of the USA is"
T(1) = {"true":"Washington DC", "dummy":{"false:"New York", "feedback":"New York is a large city in the USA, but not the capital."}}
S(2) = "."

This is to render as

The capital of the USA is [( )].

((New York)) ((Washington))

Another type of example is pure matching of missing phrases. Write the piece of text to reconstruct as

S(1) T(1) S(2) T(2) ... S(N) T(N) S(N + 1)

Then the software should display boxes [( )] between the S(i):

S(1) [(   )] S(2) [(   )] S(3) ... S(N) [(   )] S(N + 1)

and display the boxes ((T(j))) below in a random order.

The user is supposed to drag the phrases into the boxes.

Here the boxes and matching strings can have corresponding colours randomly turned on, as a form of custom hint.

General setting

The data array will look like

[S-array, T-array]

Here the S-array will be

[S(1), S(2), ..., S(N + 1)]

and the S(i) will be strings, possibly null, subject to JSON constraints and the constraint that S(N + 1) is either null or ends in a terminating punctuation mark.

The T-array will be

[T(1), T(2), ..., T(N)]

In general T(j) will be an object

{"true":acceptable answer1, "true":acceptable answer2, ..., "dummy":{"false":string1, "feedback":response1}, "dummy":{"false":string2, "feedback":response2}, ... "hint":custom_hint", ... }

Here the "true" components consist of strings each of which is an acceptable answer in the place between S(j) and S(j + 1). The object has to carry the other information in the question, namely any dummy answers and set responses, custom hints, special reset information, special scoring information. The dummy answers actually shown consist of {"false":string, "feedback":response} but response setting can be null as the default.

Five subtypes

Going beyond simply matching phrases into boxes (type A question), there are two types of added complexity, namely multiple choice, and colour coding. Colours can identify which answers relate to which box (i.e. calibrate the missing phrases a bit).

Type	Plain	Coloured
Matching	A	n/a
Check box	B	C
Complex	D	E

The colouring option clearly should be operated by the question subtype field, but may also be a custom hint. The dummy answers should be listed in the annotations.

Note on multiple correct answers: they can be indicated by a thicker line round the input box, modified when input is made.

Configuration object

This is a provisional listing of some "fields" that should occur in the configuration object, mostly with default values.

Working content:

1. (Slide type) 1
2. (question name)
3. (question type) choice/cloze
4. (question subtype) A to E
5. (equality test) non-case sensitive equality of Unicode strings
6. (display type) graphical
7. (response type) enabled
8. (hint type) i.e. go back | wikidata or other link in a new tab | custom
9. (reset type) back to question start
10. (scoring type) "unit scoring"
11. (timing type) none

Also:

1. Legacy fields: allow for some carried forward from Moodle
2. Metadata to track provenance and attribution of question. (wikidata item) to use as a tag for topic area.

In other words the working content is like:

{"slide type": , "question name": , "question type": , "question subtype": , "equality test": , "display type": , "response type": , "hint type": , "reset type": , "scoring type": , "timing type": }

"wikidata item": should be extracted from the metadata, if it is needed to generate a hint.

Legacy fields to include "usecase", "hidden", "old type", "description". Provenance fields to include "quizencodingversion", "old name", "description", also license and attribution information