<abstract>This document specifies an XMPP protocol extension that supports the exchange of structured data objects.</abstract>
&LEGALNOTICE;
<number>0204</number>
<status>Experimental</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>TO BE ISSUED</shortname>
<author>
<firstname>Dave</firstname>
<surname>Bryson</surname>
<email>dbryson@mitre.org</email>
</author>
<author>
<firstname>Dan</firstname>
<surname>Winkowski</surname>
<email>winkowsk@mitre.org</email>
</author>
<author>
<firstname>Michael</firstname>
<surname>Krutsch</surname>
<email>michael@mitre.org</email>
</author>
<author>
<firstname>Chad</firstname>
<surname>Smith</surname>
<email>chadsm@mitre.org</email>
</author>
<author>
<firstname>Jasen</firstname>
<surname>Jacobsen</surname>
<email>jasenj1@mitre.org</email>
</author>
<author>
<firstname>Marshall</firstname>
<surname>Huss</surname>
<email>mhuss@mitre.org</email>
</author>
<revision>
<version>0.1</version>
<date>2007-01-17</date>
<initials>psa</initials>
<remark>
<p>Initial XEP version; modified namespaces to adhere to XSF policy.</p>
</remark>
</revision>
<revision>
<version>0.0.3</version>
<date>2006-12-29</date>
<initials>mwh</initials>
<remark>
<p>Converting to validate against new XEP schema</p>
</remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2006-09-15</date>
<initials>deb</initials>
<remark>
<p>Edits, some reformating, Spell check</p>
</remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2006-08-30</date>
<initials>deb</initials>
<remark>
<p>First draft.</p>
</remark>
</revision>
</header>
<!-- INTRODUCTION -->
<section1topic="Introduction"anchor="intro">
<p>
While the value of IM and Multi-user chat is obvious to anyone reading this JEP, the potential for ambiguity and miscommunication
(particularly in a structured data environment) may not be. There are several domains where text communication is accompanied
by a need to exchange structured data, e.g.: a help desk dealing with trouble tickets; a financial institution dealing with trades (buy and sell orders),
an emergency scenario with first responders. The purpose of this JEP is to define a set of Collaborative Data Object (CDO) protocols
that support the exchange of structured data objects. These data objects are explicitly described by a declarative language, instantiated as
structured XML, and transported as extended XMPP stanzas. This JEP defines a protocol for exchanging these structured CDOs as
part of a session conversation (either IM or Multi-User Chat) based around a <em>strict synchronization</em> model. In a strict synchronization model,
participants will receive every change made to a CDO. An alternative synchronization model, a
<em>lazy synchronization</em>
model is also described to support users who either do not wish, or are not able because of infrastructure limitations, to receive the CDO stanzas
in real time and wish to explicitly request them.
</p>
</section1>
<!-- REQUIREMENTS -->
<section1topic="Requirements"anchor="reqs">
<p>This JEP describes a protocol that is designed to fulfill the following requirements: </p>
<p>Participants using strict synchronization will receive
<strong>every</strong> change event to the CDOs in a room or private chat.
</p>
<p>Imagine two chat clients,
<strong>A</strong> and
<strong>B</strong>,that wish to share structured data in a synchronized manner.
Both clients want to ensure they have the most up-to-date information. The two endpoints can do so by collaborating on the data using the CDO protocol.
</p>
<p>For example, let's assume the clients wish to coordinate a meeting over chat. The process may look like this:</p>
<p>In topic-focused collaboration, a group of participants come together to discuss particular categories of information. This use of a topic as a focal point is significant because it provides participants with meaningful, often unspoken, context of information. Semantic cues, manipulation capabilities, state transitions, and information presentation are all included in this context.</p>
<p>CDOs leverage topic-focused collaboration by requiring every CDO to be an instance of a type. A type is analogous to a topic because participants are given a common understanding of the information being discussed and its context. This relationship is also similar to the programming concept of a class and an object. Much like a class describes the capabilities of an object, a CDO type describes an instance.</p>
<p>CDO Description Language (CDO-DL) is the means by which a type is defined. It is meant to be a highly extensible framework through which multiple (but equivalent) definitions of type capabilities can exist. This extensibility allows users with different operating environments to collaborate consistently.</p>
<p>Some information is required for every CDO-DL to maintain consistent interpretation:</p>
<ul>
<li>
<strong>UUID</strong>: A universally unique identifier to distinguish this type from all others. This value is meant for machine use, but it may also be structured for human use.</li>
<li>
<strong>Label</strong>: The primary identifier meant for human use. This should concisely describe the data and context of a type. Although uniqueness of this field is not required, it is highly recommended.</li>
<li>
<strong>Version</strong>: The version associated with the type. As a type matures, its UUID and version will change. This also provides a mechanism for determining deprecation of previous versions.</li>
<li>
<strong>Description</strong>: A more complete description of the data and context of a type. A description can exist for individual languages.</li>
<li>
<strong>Schema</strong>: The XML Schema definition of the data associated with a type. This can either be embedded in the CDO-DL or referenced in an external URL.</li>
</ul>
<p>Beyond this core data, every CDO-DL can have multiple (but equivalent) standard-specific implementations for the remaining context of the type:</p>
<ul>
<li>
<strong>Layout</strong>: The means by which data is presented to a user. Layouts are arranged in groups, each with a unique identifier and title. Each group is capable of containing multiple equivalent standard-specific presentations to support a diverse client base, but each group must contain at least an XHTML/XForm presentation. Individual presentations can embedded or referenced in an external URL, and one layout group must be marked as the default layout through which users will initially interact with the data.</li>
<li>
<strong>Method</strong>: The operations which can be carried out on the data. Equivalent standard-specific operations can be grouped together as a single notional method with a single unique identifier and description.</li>
<li>
<strong>State</strong>: The finite states through which a data set can transition. States are individually defined along with the criteria for entering each. State transitions are also defined along with the actions they perform (such as turning on or off specific layouts and methods).</li>
The name attribute corresponds to the name of the attribute in the CDO-DL. Note: All attributes are sent as part of an item, even those not changed when
Note an event type of info. This requires all attributes for the data-sync element and items be present
</section2>
<section2topic="Query an endpoint for a list of CDOs"anchor="cdolist">
In some cases a client may be interested in the state of all CDOs belonging to a specific endpoint - for example a chat room.
<examplecaption="Client A constructs an IQ get and sends it to Server X wishing to obtain the current state of all CDOs belonging to the CDO users chatroom"><![CDATA[
Here client A, has created a packetID and set event=create in both <data-sync> and <item>. The version MUST be set to zero
<p>
Next, the message is intercepted by Server X. Server X is the IM server that both clients are connected to. When the server receives
the message, it MUST increment the version number and assign a uuid for both the <data-sync> and <item>. Once processed
Server X MUST send a copy of the message back to client A as a receipt that the message has been processed by Server X and forward the message to client B
</p>
<examplecaption="Send receipt from Server X to client A"><![CDATA[
Here client A, has set event=update on the <data-sync> and event=create on the new <item>. The version MUST be set to zero on the new item.
The message is intercepted by Server X. Server X is the IM server that both clients are connected to. When the server receives the message, it MUST increment
the version number and assign a uuid for the new <item>
</p>
<p>
Next, Server X MUST send a copy of the message back to client A as a receipt that the message has been processed by Server X and forward the message to client B
</p>
<examplecaption="Send receipt from Server X to client A"><![CDATA[
Once this is completed, both clients have a synchronized CDO message with a new item. The new item has been assigned a uuid and a version number by the server.
</section2>
<section2topic="Update an Item on an existing CDO"anchor="cdoitemupdate">
When client A wishes to update an item on an existing CDO, he sends the following information to client B
<examplecaption="Client A updates an item on an existing CDO and sends it to client B"><![CDATA[
Here client A, has set event=update on the <data-sync> and event=update on the changed <item>. Note the version is set to the current
version being edited, in this case 1, and both the <item> and <data-sync> have an existing uuid.
</p>
<p>
The message is intercepted by Server X. Server X is the IM server that both clients are connected to. When the server receives the message, it
MUST increment the version number and assign a uuid for the new <item>
</p>
<p>
Next, Server X MUST send a copy of the message back to client A as a receipt that the message has been processed by Server X and forward the message to client B
</p>
<examplecaption="Send receipt from Server X to client A"><![CDATA[
Once this is completed, both clients have a synchronized CDO message with an updated item. The updated item has the version number incremented.
<section3topic="Update Styles">
<p>
There are two types of behaviors associated with an item update: inclusive and exclusive. For an inclusive update, the content of the item element
in the CDO data synchronization packet is considered to be fully representative of the value that item will have at the end of the update operation.
This behavior results in previously set values for an item being destroyed if they are not repeated for each item update. For an exclusive update, the
content of the item element in the CDO data synchronization packet is considered to contain only the values to be modified as a result of the update
operation. This behavior results in previously set values for an item being carried over if they are not explicitly contradicted in each subsequent item update.
</p>
<p>
Assume that client A has created a CDO cdo_1. This CDO has an item item_1 with the attribute named attr_1 set. If A wants to update item_1 with a value
for the attribute named attr_2 without destroying the previously set value for attr_1, the following data synchronization packets are equivalent:
Once this is completed, both clients have retired (deleted) the CDO.
</section2>
</section1>
<section1topic="Errors"anchor="errors">
<p>
The error reporting mechanism for this specification follows the recommendations as set forth in the XMPP Core RFC. As such, when an error condition is detected,
a stanza-related error must be generated and returned to sending entity. The error condition should be described using an XMPP general condition and CDO specific
condition. Further amplification to the error condition should be provided by including the applicable subset of the data-sync message which caused the error.
</p>
<p>
Error types other than continue (cancel, modify, wait) disrupt the normal processing of CDO data-synch messages and only the associate error message
will be issued by a supporting server.
</p>
<p>
Addition of only the applicable subset of the data-sync message in an error stanza is meant to assist the sending entity in isolating what directive in the message caused the error.
Most CDO specific conditions include sufficient metadata to enable the sender to isolate the cause, but it is possible for the sender to generate messages in which this metadata is
not present. In this case, it may not be possible for the sender to determine the message subset causing the error unless that subset is included in the error.
</p>
<examplecaption="Assume the following message is sent:"><![CDATA[
The first potential cause for an error in a data syonchronization packet is the root data-sync element. An error at this level is indepedent of the content of any element descendents of the data-sync element. When this occurs, a server error sent to the recipient <strong>MUST</strong> include the data-sync element to provide context; a bandwidth-constrainted connection <strong>MAY</strong> omit the element descendants.
</p>
<examplecaption=""><![CDATA[
<messageto="aral@example.com"type="error">
<cdo:data-sync
protocol="1.0"
packetID="miles@example.com:packet-1"
event="update"
uuid="miles@example.com:instance-1"/>
<errortype="cancel">
<item-not-found/>
<cdo:no-such-instance/>
</error>
</message>
]]></example>
<p>
The second potential cause for an error is a child item element. For an item of event type create, the sender is not required to nominate a UUID for the item. If multiple items are used
in this fashion, it is not possible for the item related to the error to be identified by reference. The only way to indicate to the sender the item related to the error is by isolating that
item in the error stanza. As a result, the subset for this case is the data-sync element with all child item elements removed except the item related to the error.
</p>
<examplecaption=""><![CDATA[
<messageto="aral@example.com"type="error">
<cdo:data-sync
protocol="1.0"
packetID="miles@example.com:packet-1"
event="update"
uuid="miles@example.com:instance-1">
<itemtype="field"event="update"
uuid="miles@example.com:field-1" version="2">
<value>Imperial waltz</value>
</item>
</cdo:data-sync>
<errortype="cancel">
<item-not-found/>
<cdo:no-such-item/>
</error>
</message>
]]></example>
<section2topic="CDO specific conditions"anchor="cdoerrorconditions">
<tablecaption="Specific Conditions">
<tr>
<td>
<p>
<strong>Error Type</strong>
</p>
</td>
<td>
<p>
<strong>General Condition</strong>
</p>
</td>
<td>
<p>
<strong>Specific Condition</strong>
</p>
</td>
<td>
<p>
<strong>Description</strong>
</p>
</td>
</tr>
<tr>
<td>
<p>cancel</p>
</td>
<td>
<p>
<tt><xmpp:feature-not-implemented/></tt>
</p>
</td>
<td>
<p>
<tt><cdo:unkown-protocol-version/></tt>
</p>
</td>
<td>
<p>The protocol version for the data sync packet is unknown to the framework and cannot be processed.</p>
<p>The framework cannot create a new instance with the specified identifier because one already exists with that identifier. As a result, the framework has created a new identifier for the instance to be created.</p>
</td>
</tr>
<tr>
<td>
<p>cancel</p>
</td>
<td>
<p>
<tt><xmpp:item-not-found/></tt>
</p>
</td>
<td>
<p>
<tt><cdo:no-such-instance/></tt>
</p>
</td>
<td>
<p>The framework has no record of an instance with the specified identifier.</p>
</td>
</tr>
<tr>
<td>
<p>cancel</p>
</td>
<td>
<p>
<tt><xmpp:not-allowed/></tt>
</p>
</td>
<td>
<p>
<tt><cdo:instance-retired/></tt>
</p>
</td>
<td>
<p>The event cannot be executed on the instance because that instance has been retired.</p>
</td>
</tr>
<tr>
<td>
<p>wait</p>
</td>
<td>
<p>
<tt><xmpp:undefined-condition/></tt>
</p>
</td>
<td>
<p>
<tt><cdo:instance-is-active/></tt>
</p>
</td>
<td>
<p>The retire event cannot be executed on the instance because the instance is actively being updated.</p>
</td>
</tr>
<tr>
<td>
<p>cancel</p>
</td>
<td>
<p>
<tt><xmpp:item-not-found/></tt>
</p>
</td>
<td>
<p>
<tt><cdo:no-such-type/></tt>
</p>
</td>
<td>
<p>The framework has no record of a type with the specified identifier.</p>
<p>The framework cannot create a new item with the specified identifier because one already exists with that identifier. As a result, the framework has created a new identifier for the item to be created.</p>
</td>
</tr>
<tr>
<td>
<p>cancel</p>
</td>
<td>
<p>
<tt><xmpp:item-not-found/></tt>
</p>
</td>
<td>
<p>
<tt><cdo:no-such-item identifier="I"/></tt>
</p>
</td>
<td>
<p>The framework has no record of an item with the specified identifier for the specified instance.</p>
<p>The request cannot be executed on the item because the referenced version is outdated. The framework MAY indicate the current version in the reply.</p>
<p>The data-sync packet is not logically valid as described by the type T (see section X.3). The framework MAY include the identifier of the offending data-sync packet or item.</p>
</td>
</tr>
</table>
<p>Errors which may result from schema validation have been omitted.</p>
The CDO specific condition "invalid-constraint" enables the server to indicate logical invalidity of a data-sync packet. The use of a single condition for this purpose provides a consistent
reporting mechanism to the sender, but the invalidity must be described with the "type" attribute as follows:
</p>
<tablecaption="Invalid Constraint types">
<tr>
<td>
<p>
<strong>Type</strong>
</p>
</td>
<td>
<p>
<strong>Description</strong>
</p>
</td>
</tr>
<tr>
<td>
<p>instance-identifier-required</p>
</td>
<td>
<p>Data-sync packets of event type "update" and "retire" MUST specify the target instance.</p>
</td>
</tr>
<tr>
<td>
<p>instance-type-prohibited</p>
</td>
<td>
<p>Data-sync packets of event type "update" and "retire" MUST NOT specify an instance type.</p>
</td>
</tr>
<tr>
<td>
<p>instance-type-required</p>
</td>
<td>
<p>Data-sync packets of event type "create" MUST specify an instance type.</p>
</td>
</tr>
<tr>
<td>
<p>item-required</p>
</td>
<td>
<p>Data-sync packets of event type "update" MUST include at least one data-sync item.</p>
</td>
</tr>
<tr>
<td>
<p>items-prohibited</p>
</td>
<td>
<p>Data-sync packets of event type "retire" MUST NOT include any data-sync items.</p>
</td>
</tr>
<tr>
<td>
<p>item-event-prohibited</p>
</td>
<td>
<p>Data-sync packets of event type "create" MUST ONLY include data-sync items of event type "create."</p>
</td>
</tr>
<tr>
<td>
<p>item-identifier-required</p>
</td>
<td>
<p>Data-sync items of event type "update" and "delete" MUST include the target identifier.</p>
</td>
</tr>
<tr>
<td>
<p>item-update-style-prohibited</p>
</td>
<td>
<p>Data-sync items of event type "create" and "delete" MUST NOT specify an update style.</p>
</td>
</tr>
<tr>
<td>
<p>item-value-prohibited</p>
</td>
<td>
<p>Data-sync items of event type "delete" MUST NOT contain a value.</p>
</td>
</tr>
<tr>
<td>
<p>item-value-required</p>
</td>
<td>
<p>Data-sync items of event type "create" and "update" MUST contain a value.</p>
</td>
</tr>
<tr>
<td>
<p>item-version-prohibited</p>
</td>
<td>
<p>Data-sync items of event type "create" MUST NOT specify a version.</p>
</td>
</tr>
<tr>
<td>
<p>item-version-required</p>
</td>
<td>
<p>Data-sync items of event type "update" and "delete" MUST specify a version.</p>
</td>
</tr>
<tr>
<td>
<p>item-xpath-prohibited</p>
</td>
<td>
<p>Data-sync items of event type "update" and "delete" MUST NOT specify an XPath.</p>
</td>
</tr>
<tr>
<td>
<p>item-xpath-required</p>
</td>
<td>
<p>Data-sync items of event type "create" MUST specify an XPath.</p>
</td>
</tr>
</table>
</section2>
<section2topic="Special Case: Outdated version error"anchor="specialcases">
<p>
It is possible for a notional conflict to exist between two clients attempting to update a CDO instance. In this case, two separate clients submit data sync packets
containing at least one overlapping item. When this occurs, the first packet to arrive at the framework is executed, but the error information
reported back to the client of the second packet MAY be extended to describe the notional conflict. This additional error information is meant to facilitate
collaboration between the clients.
</p>
The additional error information provide includes:
<ul>
<li>The resource identifier of the client originating the data sync packet with which this error conflicts.</li>
<li>The timestamp of when the originating data sync packet was executed.</li>
<li>The item element of the originating data sync packet with which this error conflicts.</li>
To properly handle the protocol described in this JEP. A server side service will need to be able to process CDO packets and IQ messages.
This means at a minimum, the service will need to be able to:
</p>
<ol>
<li>Filter for data-sync and IQ protocol extentions as described above</li>
<li>Handle packet extentions that appear as a child element to the message element</li>
<li>Provide an underlying framework that can manage versioning of data-sync messages. If designed accordingly, it may be possible for this framework to be re-used by clients as well.</li>
</ol>
<p>
Additionally, a server MUST ignore any 'to' address on a cdo related IQ "set", and MUST treat any cdo IQ "set" as applying to the sender.
</p>
</section2>
<section2topic="Client"anchor="client">
<p>For a client to be able to exchange CDO messages it will need to provide capabilites similar to those described above: </p>
<ol>
<li>Filter and respond to data-sync and IQ protocol extentions described in this specification</li>
<li>Properly handle packet extentions that appear as a child elements to the message element</li>
<li>Provide an underlying framework that can manage the version of data-sync messages. (see 3. above)</li>
<li>Provide a form based GUI to properly construct the CDO messages.</li>
<li>Provide the ability to construct data-sync related IQ messages</li>
</ol>
<p>
Additionally, a client SHOULD check the "from" address of a cdo query (incoming IQ of type "result" containing a cdo type) to ensure that it is
from a trusted source; specifically, the stanza MUST either have no 'from' attribute (i.e., implicitly from the server) or have a 'from' attribute whose
value matches the user's bare JID (of the form <user@domain>) or full JID (of the form <user@domain/resource>); otherwise, the client
<p>Until this specification advances to a status of Draft, its associated namespace shall be "http://www.xmpp.org/extensions/xep-0204.html#ns" (along with relevant "sub-namespaces" in which "#ns" is followed by the "-" character and a subname string); upon advancement of this specification, the XMPP Registrar shall issue a permanent namespace in accordance with the process defined in Section 4 of &xep0053;.</p>
<p>Note: As this protocol is currently used in implemented software, the namespaces are of the form "http://www.mitre.org/mtp/cdo", "http://www.mitre.org/mtp/cdo/types", etc.</p>
