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:

]]>

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

]]>

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

]]>

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.


	]]>     

	]]>

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:

]]>

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.


	...
      ...]]>

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

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


	    

	   . . . 

	  

	   . . .       

	   . . . 

	   . . . 

	   . . . 

	  

	  ]]>

Question

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

Attributes None.

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

Examples


	    
	    How many XML programmers does it take to change a lightbulb?  
	  ]]>

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

]]>

Answer

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


	    
	    
	  A vegetable.
	    
	  No, don't be silly.
	    
	  ]]>
	    
	    
	    
	  No, don't be silly.
	    
	  Yes, your answer was correct.

	  ]]>

Response

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

Attributes None.

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

Examples


	    2.314]]>

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


	    Incorrect; bananas are not blue.]]>

Hint

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

Attributes None

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

Examples


	    Bananas are fruit.]]>

Key

Description The key tag contains the correct answer to an item.

Attributes Answer. 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


	    
	    
	  Bananas are fruit.]]>