<?xml version="1.0" encoding="UTF-8"?>
<!--$Id: tutor_message_v4.dtd,v 1.1.1.1 2012/10/24 23:23:21 mkomisin Exp $-->
<!--
     This DTD specifies a protocol for messages among tools and tutoring translators 
     and agents.  The goal is to standardize the messaging format in order to 
     simplify the translation process for simple tutors and pseudo-tutors and tools 
     that want to use them.  Other kinds of programs that might use these messages 
     include playback processors or other instances of collaborating tools.  Based 
     on the model proposed in 'An Architecture For Plug-In Tutor Agents' 
     (Ritter, Koedinger 1996) -->
<!--
     Tutor messages may be from educational tools or from optional tutoring software 
     that observes user actions in the tool and may respond to them.-->
<!--
     The notion of separating ui events and semantic events is taken from the proposed 
     IEEE LTSC specification (Ritter)-->

<!-- 
     The tool or tutor needs to generate a tutor_related_message_sequence.
     Attributes:
        version_number : should be an integer that respresents the DTD version.
        "2" : February 2005
        "3" : June 2005 (not supported)
    "4" : March 2006
-->
<!ELEMENT tutor_related_message_sequence 
    (tool_message | tutor_message | context_message | message)+>
<!ATTLIST tutor_related_message_sequence
    version_number CDATA #IMPLIED
>

<!-- 
     A tool_message is generated by a tool and typically describes a user action on that tool.
     Attributes:
        context_message_id : used to group the dataset message with the corresponding tool, 
        tutor and plain messages.
-->
<!ELEMENT tool_message 
    (meta?, problem_name?, (ui_event | semantic_event)+, event_descriptor*, custom_field*)>
<!ATTLIST tool_message
    context_message_id CDATA #IMPLIED
>

<!--
     A tutor_message conveys a tutors evaluation of an attempt, a hint or a scripting 
     directive to the tool.
     Attributes:
        context_message_id : used to group the dataset message with the corresponding tool,
        tutor and plain messages.
-->
<!ELEMENT tutor_message 
    (meta?, problem_name?, (ui_event | semantic_event)+, event_descriptor*, action_evaluation*, 
    tutor_advice*, skill*, interpretation*, custom_field*)>
<!ATTLIST tutor_message
    context_message_id CDATA #IMPLIED
>

<!--
     A problem_name identifies the transaction context in terms of the application.  
     The element's structure is loosely specified:  some applications may have a 
     hierarchical problem-naming scheme and so would have to specify here course, 
     unit and section in addition to a specific problem name.  Other applications 
     might identify problems with a simple string or URI. The intent is to unambiguously 
     tell what problem the student was working on. Some messages (lock widgets, e.g.) 
     may be unrelated to any problem; in these cases the problem name may be omitted.
-->
<!ELEMENT problem_name ANY>

<!--
     The ui_event element(s) makes available a place for a tool to log low-level 
     user interface events.  It might want a special format for machine processing 
     (aimed at fine-grained reproduction on playback, e.g.) or it could be a description 
     intended for human readers.  Examples might include a single key press, a mouse 
     movement, etc.  
-->
<!ELEMENT ui_event ANY>
<!ATTLIST ui_event
    id CDATA #IMPLIED
    name CDATA #IMPLIED
>

<!--
     The semantic event is an event (at a higher level than a ui_event) of interest 
     to, e.g., a tutor, a higher-level playback processor or a collaborating tool.  
     The content of the event is unspecified in this DTD:  it may be a human-readable 
     or domain-specific representation of the event.  
     Attributes:
        transaction_id : uniquely identifies the event within the session.  
        name : more like a type of the event
                examples of tool events:  ATTEMPT*, HINT_REQUEST*, START_TUTOR, STOP_TUTOR
                examples of tutor events: RESULT*, HINT_MSG*  
        trigger : should be USER if the triggering event was a user action.
        subtype : relates to the name attribute

    * Note:  the tool and tutor events marked by an asterisk are expected by
    some of the DataShop analysis code.  Though you can put any string in this field,
    conforming to these strings may be more useful.
        Expected pairs are: ATTEMPT/RESULT or HINT_REQUEST/HING_MSG
-->
<!ELEMENT semantic_event ANY>
<!ATTLIST semantic_event
    transaction_id CDATA #REQUIRED
    name CDATA #IMPLIED
    trigger (USER | DATA) #IMPLIED
    subtype CDATA #IMPLIED
>

<!--
     An event_descriptor contains the details of a single observable (visible, 
     audible, etc.) change in the state of a user interface.  This descriptor will 
     usually detail changes initiated by users, but tutors, e.g., could change the 
     state of a tool's interface. In particular, for hint responses, the event 
     descriptor should describe the correct action on this step: the tool may highlight 
     the indicated selection in conjunction with displaying the hint text.
     Attributes:
        event_id : Where multiple ui_events or semantic_events are in a message, 
                   an event_descriptor can point to the particular XXX_event via 
                   this reference.
-->
<!ELEMENT event_descriptor (selection*, action*, input*)>
<!ATTLIST event_descriptor
    event_id IDREF #IMPLIED
>
<!--
     Examples of tool actions could be ButtonPressed, UpdateTextArea, PourSolution, etc.  
     An example of a tutor action could be to update a textarea or highlight a tool widget.
     Attributes:
        id : unique identifier, basically ignored by DataShop code, not stored in database
        type : distinguishes the role this particular action plays with respect to the other SAIs
-->
<!ELEMENT action (#PCDATA)>
<!ATTLIST action
    id CDATA #IMPLIED
    type CDATA #IMPLIED
>
<!--
     A selection is the user interface widget or other element indicated when a 
     user takes an action.  Some actions will involve multiple selections; 
     e.g. a PourSolution action in a lab might involve 2 selected solutions.
     Attributes:
        id : unique identifier, basically ignored by DataShop code, not stored in database
        type : distinguishes the role this particular selected item plays in an action
               having multiple selected items; e.g. a PourSolution action could 
               have a solution of type "source" and one of type "recipient".
-->
<!ELEMENT selection (#PCDATA)>
<!ATTLIST selection
    id CDATA #IMPLIED
    type CDATA #IMPLIED
>
<!--
     Input from a tool is generally user input, e.g., the text typed into a textarea 
     widget. Input from a tutor might be text that the tool should display in a textfield.
     Attributes:
        id : unique identifier, basically ignored by DataShop code, not stored in database
        type : distinguishes the role this particular input plays with respect to the other SAIs
-->
<!ELEMENT input (#PCDATA)>
<!ATTLIST input
    id CDATA #IMPLIED
    type CDATA #IMPLIED
>

<!--
    An action_evaluation is the result of a tutor's check to see whether user input 
    was correct.  
    Examples of action_evaluation content include CORRECT*, INCORRECT*, HINT*, 
        BUG, GLOSSARY_ITEM.
    * Note:  the action evaluations marked by an asterisk are expected by
    some of the DataShop analysis code.  Though you can put any string in this field,
    conforming to these strings may be more useful. 
    Attributes:
        hint_id : unique id of the HINT, only used if the value is HINT
        current_hint_number : only used if the value is HINT
        total_hints_available : only used if the value is HINT
        classification : a way to classify the response
-->
<!ELEMENT action_evaluation (#PCDATA)>
<!ATTLIST action_evaluation
    hint_id CDATA #IMPLIED
    current_hint_number CDATA #IMPLIED
    total_hints_available CDATA #IMPLIED
    classification CDATA #IMPLIED
>
<!--
     The tutor_advice contains the body of a HINT_MSG, the success or buggy message 
     for a RESULT, etc.
-->
<!ELEMENT tutor_advice (#PCDATA)>

<!--
     Updates to skill level(s) may be generated by a tutor as a user completes a 
     step in a problem.
     Attributes:
        probability : optional
-->
<!ELEMENT skill (name, category?, model_name*)>
<!ATTLIST skill
    probability CDATA #IMPLIED
    buggy CDATA #IMPLIED
>
<!ELEMENT category (#PCDATA)>
<!ELEMENT model_name (#PCDATA)>

<!--
     Cognitive tutors can have multiple interpretations of an action.

     If any interpretations are included, there should be one and only one chosen
     interpretation. The skill goes with the chosen interpretation.

     For a correct response, there is most likely, one interpretation with just a correct
     step sequence.

     For an incorrect response, there will be both an incorrect and a correct 
     step sequence.
-->
<!ELEMENT interpretation (correct_step_sequence?, incorrect_step_sequence?)>
<!ATTLIST interpretation
    chosen (true|false) #IMPLIED
>
<!ELEMENT correct_step_sequence (step+)>
<!ATTLIST correct_step_sequence
    ordered (true|false) #IMPLIED
>
<!ELEMENT incorrect_step_sequence (step+)>
<!ATTLIST incorrect_step_sequence
    ordered (true|false) #IMPLIED
>
<!ELEMENT step (step_info, rule*)>
<!ELEMENT step_info (#PCDATA)>
<!ELEMENT rule (#PCDATA)>


<!--
     A specific tutor might have more information that the fields in this
     DTD allow for.  The custom field element is used for that extra information,
     e.g. name:System-Equation value: y=6x - 8
-->
<!ELEMENT custom_field (name, value)>
<!ELEMENT value (#PCDATA)>


<!--
     A context_message conveys information about the tutoring and study context:  it may 
     describe the exercise in its global context of school, course, etc. It may 
     include information that a course management system needs to select a 
     next exercise.
     Attributes:
        context_message_id : used to group the dataset message with the corresponding tool,
        tutor and plain messages.
        name: used to indicate where the student is in the process of starting a tutor/problem, etc.
            examples: START_TUTOR, START_PROBLEM, STOP_PROBLEM, 
            CONTINUE_PROBLEM, FINISH_PROBLEM
-->

<!ELEMENT context_message 
    (meta?, class?, dfa*, dataset?, skill*, condition*, custom_field*) >
<!ATTLIST context_message
    context_message_id CDATA #IMPLIED
    name CDATA #IMPLIED
>

<!-- 
    An class is the institutional or other organizational contextual information 
    where this activity is taking place.
-->
<!ELEMENT class (name?, school?, period?, description?, instructor*)>

<!-- 
    The name of the school, such as Carnegie Mellon University, or Shadyside Academy.
-->
<!ELEMENT school (#PCDATA)>

<!-- 
    The name of the period for this class.  Used as was to further differeniate between classes.
    For example given a class 27-503; period A, period B.
-->
<!ELEMENT period (#PCDATA)>

<!--  
    The instructor is the name of the instuctor. 
-->
<!ELEMENT instructor (#PCDATA)>

<!--
     Difficulty factors analysis is data associated with this problem.  We recommend 
     data of this sort, if available, be included with information logged by a START_PROBLEM entry.
-->
<!ELEMENT dfa ANY>

<!-- 
    The dataset element provides hiarchal information about the data.  It contains the level attribute which
    is a hiarachal structure in which problems exist.  It's purpose is to show the contextual structure of where
    problems exist inside of the tutor structure.
--> 
<!ELEMENT dataset (conversion_date?, converter_info?, name, level) >

<!--
    The conversion_date element provides the date the raw data was converted into this xml format.
    Example: 2007/06/29
-->
<!ELEMENT conversion_date (#PCDATA)>

<!--
    The converter_info element provides the name, version and release date of the converter tool.
    Example: Geometry Protocol Translator 4.11 June 27, 2007
-->
<!ELEMENT converter_info (#PCDATA)>

<!-- 
    A level refers to the structure of the dataset.  It will help provide the contextual information that 
    represents the hierarchical information.  Given that level can contain a level this allows a flexible 
    hierarchy of any type.  Examples of a level type include: chapter, unit, section, posttest, pretest.  
    Levels indicate where a problem falls inside of a dataset. 
-->
<!ELEMENT level (name, level?, problem?) >
<!ATTLIST level 
     type CDATA #IMPLIED
>
 
<!-- 
    A problem is a group of steps with one question. 
    The tutorFlag attribute was added so that a problem can easily be noted as either tutor or test.
    It can even be noted more specifically as pre-test or post-test.
    However, if a problem doesn't easily fall into either of these categories, but somewhere in between,
    the the tutorFlag can be set to 'other' and then the other field can specify where the problem falls
    in the tutor - test spectrum. (Other attribute is ignored unless tutorFlag is set to other.)
    Note that these attributes are optional.  The default value will be tutor.
-->
<!ELEMENT problem (name, context?)>
<!ATTLIST problem 
     tutorFlag (tutor|test|pre-test|post-test|other) #IMPLIED
     other CDATA #IMPLIED
>
<!-- 
    Any contextual information that can be provided about the problem, a description or the problem text 
    for example.
-->
<!ELEMENT context (#PCDATA)>

<!-- 
    Condition is used to indicate a study specific variable.  This can be used
    to easily identify samples for comparision.  For example if a study dataset has a group of students that
    get story problems and a group that gets only formulatic problems then the different problem types should
    contain either a condition with name "story_problem" or one with name "formulatic_problem".
-->
<!ELEMENT condition (name, type?, description?) >


<!--
     The message element is a facility for arbitrary communications content to be 
     accommodated in this DTD.  A message might contain one or more property elements.
     Attributes:
        context_message_id : used to group the dataset message with the corresponding tool,
        tutor and plain messages.
-->
<!ELEMENT message ANY>
<!ATTLIST message
    context_message_id CDATA #IMPLIED>
<!-- 
    A property is a name-value pair. The value might be a list of entries.
-->
<!ELEMENT property (#PCDATA|entry)*>
<!ATTLIST property
    name CDATA #REQUIRED>
<!--
    An entry is a single value in a list of entries.
-->
<!ELEMENT entry (#PCDATA)>


<!--
    Meta level data.  This block of data may be known to the agents, translators or tools without needing
    it to be encoded in the message itself.  However, if such data is not available, it can be encoded in 
    the message, although it is really part of the communication. Given potential differences in location 
    of agents and tools (often experienced with a web-based tool), time zone is required.

    The user id as a flag to indicate whether it has already been anonymized or not.
        The default value is false, but if set to true, then the DataShop will not re-anonymize the
        user id.
-->
<!ELEMENT meta (user_id, session_id, time, time_zone)>
<!ELEMENT user_id (#PCDATA)>
<!ATTLIST user_id
    anonFlag (true|false) #IMPLIED>
<!ELEMENT session_id (#PCDATA)>
<!ELEMENT time (#PCDATA)>
<!ELEMENT time_zone (#PCDATA)>


<!-- 
    The following elements are some of the more standardized elements that
    are used multiple places. 
-->
<!ELEMENT name (#PCDATA)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT type (#PCDATA)>