Connexions

You are here: Home » Content » QML 1.0 language specification

Recently Viewed

This feature requires Javascript to be enabled.

QML 1.0 language specification

Summary: Release 1.0 -- Initial release.

Warning:

This module contains Connexions documentation which is out-of-date. The contents of this module are provided here for historical purposes only and should not be considered accurate for the current version of the Connexions website. Please visit the help page for up-to-date information about the Connexions website, including support for viewing and authoring content and the CNXML language. If you have any additional questions or cannot find the answer to your question, please contact techsupport@cnx.org and we will be happy to assist in any way we can.

Document History

Release 1.0 - Initial release.

Introduction

This document contains the specification for the Questions Markup Language (QML). It is the definitive reference for the language and takes precedence over all other documents, including the DTD.

QML is an XML application created for the purpose of marking up learning assessment items for the Connexions Project. The language is concerned with the semantic content of the information and attempts to enforce separation of content and presentation. It contains few (if any) elements that deal with style or presentation. Decisions about how to display QML should be made elsewhere.

Document Type

QML documents must be well-formed XML documents, meaning that they must conform to the World Wide Web Consortium (W3C)'s definition of a valid XML document. In order to be considered valid QML, a document must also declare itself using a Document Type Declaration.

The Document Type Declaration (DTDs) for QML differs depending on whether you are using QML by itself or with other language(s). If you are using QML with other languages, you will also need to use namespaces (discussed in the following section).

Document Type Declarations are provided here for QML by itself, QML with CNXML, and QML with CNXML and MathML. If you are using QML with a language not listed here, you will need to create your own DTD.

In addition, you may need to alter one word in the DTDs below depending on whether you are using a problemset or an item as your base tag. If you are using a problemset as the base tag, you need to replace the word "item" in the second line with the word "problemset".

If you are using QML by itself, put the following three lines at the top of your document:


<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE item PUBLIC "-//CNX//DTD QML 1.0//EN"
"http://cnx.rice.edu/cnxml/0.5/DTD/qml.dtd">


If you are using both QML and CNXML, use the following three lines:



<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE document PUBLIC "-//CNX//DTD CNXML 0.5 plus QML//EN"
"http://cnx.rice.edu/cnxml/0.5/DTD/cnxml_qml.dtd">


If you are using MathML as well as CNXML, use the following three lines:



<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE document PUBLIC "-//CNX//DTD CNXML 0.5 plus MathML plus QML//EN"
"http://cnx.rice.edu/cnxml/0.5/DTD/cnxml_mathml_qml.dtd">


Namespaces

One of the benefits of using XML is that it allows you to unambiguously combine different XML languages within the same document by the use of namespaces (See the W3C's recommendation, Namespaces in XML).

It is possible to declare a default namespace by including the xmlns attribute in the root node (either problemset or item for QML). The attribute contains a unique identifier (usually a uri). It is important that the proper value of this attribute be used consistently. The namespace identifier for QML is http://cnx.rice.edu/qml/1.0. So for a document that only contains QML, the opening module tag should look like one OF the following, depending on whether your root tag is problemset or item.


<problemset xmlns="http://cnx.rice.edu/qml/1.0". . . >

<item xmlns="http://cnx.rice.edu/qml/1.0". . . >


However, if you are using QML with another language, you must also declare a prefix (for example, foo) using the attribute xmlns:foo and the same value that you would use on the default namespace. You can then indicate which tags come from a particular namespace or language by prefixing each tag with a foo:. Thus, an item tag in foo's namespace would be written using <foo:item> and </foo:item>. The default namespace however, allows you to omit the prefix for that particular namespace and continue using <item> as you had previously. However, if you are using more than one language, you will need to use prefixes with all namespaces but your default namespace. For example, if you were using QML, MathML, and CNXML and wanted CNXML to be your default namespace, you would declare as follows in the CNXML root tag, module:



<document xmlns="http://cnx.rice.edu/cnxml"
xmlns:q="http://cnx.rice.edu/qml/1.0"
xmlns:m="http://www.w3.org/1998/Math/MathML". . .>


You would then need to preface each QML tag in the document with "q:" and each MathML tag in the document with "m:" but would not need to preface the CNXML tags, because they are the default namespace.



<list>...</list>
<q:item id='item01'>...</q:item>


If you are adding other language(s) to a QML document, you will probably want QML to be the default namespace; if you are adding QML to a document in another language, you will probably want the original language to be a default namespace.

Using QML with CNXML

QML within a CNXML document consists of one QML item tag encased within a CNXML exercise tag.

Tags

The problemset and item tags are the two base tags. Although either may be used as a base tag, the problemset tag is used to contain a set of items and the item tag is used to contain a single item.

Problemset

Description

The problemset tag is the root tag for a set of items.

Attributes

• id - A unique identifier for the problemset
• Optional

Children

The only children of the problemset tag are item tags. One or more item tags must appear within the problemset tag.

Examples



<problemset id="math_set_1">
<item id="item1" type="single-response">
.
.
.
</item>
<item id="item2" type="single-response">
.
.
.
</item>

</problemset>


Item

Description

The item tag is the base tag for a single item. Items may be placed into a document singly or contained within a problemset.

Attributes

• id - a unique identifier for the item
• Required
• type
• Required
• Possible values:
• single-response (for multiple-choice, true/false, etc.)
• multiple-response (where two or more options must be selected)
• text-response (a string of text or a numerical answer)
• ordered-response (multiple-response for which order of the selected responses is important)

Children

• The first child of an item tag must be a question tag.
• It may be followed by, in this order,
• One or more optional resource tags;
• One or more optional answer tags;
• One or more optional hint tags;
• One optional feedback tag;
• And finally, one optional key tag.

Examples



<item id="item1" type="single-response">

<question> . . . </question>

<resource uri="http://www.bananas.com" />

<hint> . . . </hint>

<feedback id='general'> . . . </feedback>

</item>


Question

Description

The question element contains the question being asked of the learner in plain text or embedded markup.

None.

Children

A question tag may contain embedded markup (including plain text).

Examples



<question>
How many XML programmers does it take to change a lightbulb?
</question>


Resource

Description

Contains a URI which is a pointer to external resources relevant to the item (such as a dataset).

Attributes

• URI
• Required
• The location of the resource file.
• id - a unique identifier for the resource
• Optional

Children

The resource tag is an empty tag and has no children.

Examples



<resource uri="www.lightbulb.com/dataset.txt" id="res1" />


Description

Contains the response options to a question.

Attributes

• id
• Recommended for single-response, multiple-response, and ordered-response. May not contain commas, as commas are used to separate answer IDs when referring to them in the key.
• Optional for text-response. May not contain commas (see above).

Children

May contain zero or one response tags followed by 0, 1, or 2 feedback tags. In the case of one response tag, it may only have one feedback tag containing the feedback corresponding to that response. In the case of 0 response tags, it may have 0 feedback tags, 1 feedback tags (feedback for either a correct or incorrect answer) or 2 feedback tags (feedback for a correct answer and feedback for an incorrect answer). (General feedback, supplied to the user regardless of correctness or incorrectness of the user's answer, goes in the general feedback tag, which follows the hint tag.)

Examples



<response>A vegetable.</response>

<feedback>No, don't be silly.</feedback>

<feedback correct="no">No, don't be silly.</feedback>



Response

Description

The response tag contains one of the response options for the question.

None.

Children

A response tag may contain embedded markup (including plain text).

Examples



<response>2.314</response>


Feedback

Description

The feedback tag within a response element contains feedback specific to the accompanying response option (or feedback specific to a correct or incorrect answer, if there is no accompanying response option). The feedback tag in an item element follows the response and hint elements and contains feedback to be shown to the user regardless of his or her answer.

Attributes

• Correct
• Recommended for text-response items to determine correct and incorrect answers (correct="yes" vs. correct="no"), when feedback tag is contained within a response.
• Optional for other item-types.
• Optional when not contained within a response.

Children

A feedback tag may contain embedded markup (including plain text).

Examples



<feedback>Incorrect; bananas are not blue.</feedback>


Hint

Description

The hint tag contains a hint to be given to the user upon request.

None

Children

A hint tag may contain embedded markup (including plain text).

Examples



<hint>Bananas are fruit.</hint>


Key

Description

The key tag contains the correct answer to an item.

Attributes

• Recommended for single-choice, multiple-choice, and ordered-response types.
• Content corresponds to the id(s) of the correct answer(s) for these response types.
• Text-response uses embedded markup rather than an attribute.

Children

A key tag may contain embedded markup (including plain text) for text-response questions.

Examples



<key>Bananas are fruit.</key>


Content actions

PDF | EPUB (?)

What is an EPUB file?

EPUB is an electronic book format that can be read on a variety of mobile devices.

My Favorites (?)

'My Favorites' is a special kind of lens which you can use to bookmark modules and collections. 'My Favorites' can only be seen by you, and collections saved in 'My Favorites' can remember the last module you were on. You need an account to use 'My Favorites'.

| A lens I own (?)

Definition of a lens

Lenses

A lens is a custom view of the content in the repository. You can think of it as a fancy kind of list that will let you see content through the eyes of organizations and people you trust.

What is in a lens?

Lens makers point to materials (modules and collections), creating a guide that includes their own comments and descriptive tags about the content.

Who can create a lens?

Any individual member, a community, or a respected organization.

What are tags?

Tags are descriptors added by lens makers to help label content, attaching a vocabulary that is meaningful in the context of the lens.

| External bookmarks