moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-12-22 15:48:52 -05:00
Code Issues Releases Wiki Activity
36cc1feddd
xeps/xep-0204.xml
Emmanuel Gil Peyrot 7a64b7b1ed Remove spaces at the end of CDATA blocks in all XEPs. 
sed -i 's/^\s\+]]>/]]>/g' xep-*.xml
2017-02-16 19:37:21 -06:00

1859 lines
72 KiB
XML
Raw Blame History

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Collaborative Data Objects</title>
<abstract>This document specifies an XMPP protocol extension that supports the exchange of structured data objects.</abstract>
&LEGALNOTICE;
<number>0204</number>
<status>Deferred</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 published 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 -->
<section1 topic="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 -->
<section1 topic="Requirements" anchor="reqs">
<p>This JEP describes a protocol that is designed to fulfill the following requirements: </p>
<ol>
<li>Determine the ability for clients and servers to support and exchange collaborative data objects</li>
<li>Enable the exchange of structured data objects between clients</li>
<li>Define a protocol that supports the synchronization of structure data among participating clients. Currently
the protocol is based on a strict synchronization model where users will receive every change made to a CDO.
Future versions of the protocol may contain a <em>lazy</em> synchronization model that may relax the current approach.
</li>
<li>Operate in both private and group chat</li>
</ol>
<p>Future enhancements may provide the ability to:</p>
<ul>
<li>Query room for active CDOs</li>
<li>Query room history - results in CDO events for playback (per CDO or for all CDOs)</li>
<li>Register methods to a CDO</li>
<li>Register synchronization preference with framework (strict, lazy) CDO</li>
<li>Method invocation request to framework to execute and return response</li>
</ul>
</section1>
<!-- USAGE MODEL -->
<section1 topic="Usage Model" anchor="usemodel">
<p>Here is a high-level description of the flow between two clients exchanging information using the CDO protocol.</p>
<section2 topic="Strict Synchronization mode" anchor="strictmode">
<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>
<ol>
<li>Client
<strong>A</strong> creates a new meeting that contains structured data such as the title of the meeting, participant e-mail list, start time, date,
length, and location.
</li>
<li>Client
<strong>A</strong> sends the meeting information to client B over normal chat.
</li>
<li>When client
<strong>A</strong> adds, updates, or deletes an item on the meeting, the changes are reflected to Client
<strong>B</strong>
</li>
<li>Similarily, when client
<strong>B</strong> adds, updates, or deletes an item on the meeting, the changes are reflected to Client
<strong>A</strong>
</li>
</ol>
<p>The above example describes the main flow between two clients. However a more detailed description of the flow using the example above would look
like the following below. In this example we also show the interaction with the server (server
<strong>X</strong>). Server
<strong>X</strong> is the IM
server that both client
<strong>A</strong> and
<strong>B</strong> are connected to.
</p>
<ol>
<li>Client
<strong>A</strong> wishes to send information about a new meeting to client
<strong>B</strong>
</li>
<li>Client
<strong>A</strong> first sends an IQ packet to client
<strong>B</strong> to determine if the client supports the CDO protocol.
</li>
<li>Client
<strong>B</strong> responds to the IQ packet from client
<strong>A</strong> confirming that it does support the CDO protocol.
</li>
<li>Client
<strong>A</strong> creates a new meeting that contains structured data such as the title of the meeting and the location.
</li>
<li>When client
<strong>A</strong> sends the CDO to client
<strong>B</strong>, the message is intercepted by server
<strong>X</strong>.
</li>
<li>Server
<strong>X</strong>, examines the message from client
<strong>A</strong> and determines that it is a CDO create message. The server
increments the version of the meeting items and forwards the message to client
<strong>B</strong>.
</li>
<li>When client
<strong>A</strong> adds, updates, or deletes an item on the meeting, the changes are first interrogated by server
<strong>X</strong>
and then forwarded to Client
<strong>B</strong>
</li>
<li>Similarily, When client
<strong>B</strong> adds, updates, or deletes an item on the meeting, the changes are first interrogated by server
<strong>X</strong>
and then forwarded to Client
<strong>A</strong>
</li>
<li>After processing the message from Client
<strong>A</strong>, Server
<strong>X</strong> will return a receipt to Client
<strong>A</strong>.
The receipt contains the UUID for the new item along with confirming the event was valid.
</li>
</ol>
</section2>
<section2 topic="Lazy Synchronization mode" anchor="lazymode">
<p>
Lazy synchronization is a proposed alternate synchronization scheme that is appropriate for entities 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. Under lazy synchronization, entities are only notified that CDOs have been created, retired or
that the existing CDOs that they keep track of have been updated and are now outdated. The details behind these
events are not transmitted. Explicit action is required to resynchronized to the current state for any specific CDO identifier or
change to the strict synchronization scheme. Lazy synchronization is set per endpoint (groupchat room).
</p>
</section2>
</section1>
<!-- DESCRIPTION LANGUAGE -->
<section1 topic="Description Language" anchor="descriptionLanguage">
<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>
</ul>
</section1>
<!-- PROTOCOL -->
<section1 topic="Protocol" anchor="protocol">
<p>The CDO protocol uses the namespace:
<strong>http://www.xmpp.org/extensions/xep-0204.html#ns</strong>
</p>
<p>
<strong>&lt;data-sync/&gt;</strong> is the root element and
<strong>MUST</strong> be contained within a message stanza
<strong>&lt;message/&gt;</strong> element. When the
<strong>&lt;data-sync&gt;</strong> element is present in the
<strong>&lt;message&gt;</strong>,the message
<strong>MUST</strong> not contain a
<strong>&lt;body&gt;</strong> element.
</p>
<example caption="Message with data-sync element"><![CDATA[
<message to='romeo@example.net/orchard'
from='juliet@example.com/balcony'
type='chat' xml:lang='en'>
<data-sync protocol="1.0" uuid="" type="cdo:Meeting"
event="create" xmlns="http://www.xmpp.org/extensions/xep-0204.html#ns">
<item type="field" uuid="" event="create" ref="/Meeting/Title" version="0">
<value>This is a new meeting</value>
</item>
</data-sync>
</message>
]]></example>
<p>The
<strong>&lt;data-sync&gt;</strong> element
<strong>may </strong>contain
<strong>&lt;item&gt;</strong> elements.The attributes of the
<strong>&lt;data-sync&gt;</strong> element maintain high-level information about the enclosed
<strong>&lt;item&gt;</strong> elements to help synchronize information exchanged between clients.
</p>
<table caption="Attributes in the &lt;data-sync&gt; element:">
<tr>
<td>
<strong>Attribute</strong>
</td>
<td>
<strong>Description</strong>
</td>
<td>
<strong>Mandatory?</strong>
</td>
</tr>
<tr>
<td> protocol
</td>
<td>
The version of the CDO exchange protocol
</td>
<td>
Yes
</td>
</tr>
<tr>
<td>
uuid
</td>
<td>
A universal unique identification number
</td>
<td>
Yes
</td>
</tr>
<tr>
<td>
packetID
</td>
<td>
a unique number created by the client to identify the cdo request, referenced by the framework
in responses to a client (errors, responses to events). The packetID of the receipt MUST match the original data-synch message from the sender.
</td>
<td>
Yes
</td>
</tr>
<tr>
<td>
type
</td>
<td>
the uuid of the CDO definition (CDO-DL)
</td>
<td>
mandatory on create event and info event, otherwise forbidden
</td>
</tr>
<tr>
<td>
event
</td>
<td>
cdo event type: create, update, retire, info
</td>
<td>
Yes
</td>
</tr>
</table>
<table caption="Attributes in the &lt;item&gt; element:">
<tr>
<td>
<p>
<strong>Attribute</strong>
</p>
</td>
<td>
<p>
<strong>Description</strong>
</p>
</td>
<td>
<p>
<strong>Mandatory?</strong>
</p>
</td>
</tr>
<tr>
<td>
<p>uuid</p>
</td>
<td>
<p>assigned ID of the field instance at creation time</p>
</td>
<td>
<p>Yes</p>
</td>
</tr>
<tr>
<td>
<p>type</p>
</td>
<td>
<p>distinguishes the type of field (allowed children may vary)</p>
</td>
<td>
<p>No</p>
</td>
</tr>
<tr>
<td>
<p>ref</p>
</td>
<td>
<p>xpath reference to the element</p>
</td>
<td>
<p>mandatory on create event and info event, otherwise forbidden</p>
</td>
</tr>
<tr>
<td>
<p>event</p>
</td>
<td>
<p>identified action on the item: create, update, delete, and info with update as default</p>
</td>
<td>
<p>Yes</p>
</td>
</tr>
<tr>
<td>
<p>version</p>
</td>
<td>
<p>integer version number of item being changed</p>
</td>
<td>
<p>Yes</p>
</td>
</tr>
<tr>
<td>
<p>updateStyle</p>
</td>
<td>
<p>indicates inclusive or exclusive update style with exclusive as the default</p>
</td>
<td>
<p>No</p>
</td>
</tr>
</table>
<p>Each &lt;item&gt; <strong>may</strong> contain:
</p>
<ul>
<li>
<p> 0 or 1 (0..1)
<strong>&lt;value&gt;</strong> elements with content corresponding to the change to the identified CDO instance element contents
</p>
</li>
</ul>
<example caption="Value elements"><![CDATA[
<item type="field" uuid="" event="create" ref="/Meeting/Title" version="0">
<value>This is a new meeting</value>
</item>]]></example>
<ul>
<li>
<p> 0 or unbounded (0..*)
<strong>&lt;attribute&gt;</strong> elements.
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
using the updateStyle exclusive.
</p>
</li>
</ul>
<example caption="Attribute elements"><![CDATA[
<item type="field" uuid="" event="create" ref="/Meeting/Time/Start" version="0">
<attribute name="date">28 May 2006</attribute>
</item>]]></example>
</section1>
<!-- USE CASES -->
<section1 topic="Use Cases" anchor="usecases">
<section2 topic="Query a client to determine if it supports a CDO message" anchor="queryforcdosupport">
<p>
Client A should send an IQ packet to another client (client B) before exchanging CDO messages to determine
if client B supports CDO processing. This is accomplished using Service Discovery as described in &xep0030;.
</p>
<p>
NOTE: This assumes we register our information in the Jabber registrar. Here is an example of the exchange
between two clients: See Service Discovery for specific packet requirements
</p>
<example caption="Client A construct an IQ packet and sends it to Client B"><![CDATA[
<iq type='get'from='joe@mitre.org/Desktop' to='bob.mitre.org/Laptop'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>]]></example>
<example caption="Client B receives the packet and responds with the following"><![CDATA[
<iq type='result'
from='bob.mitre.org/Laptop'
to='joe@mitre.org/Desktop'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<identity
category='cdo'
type='text'
name='Collborative Data Objects'/>
<feature var='http://www.xmpp.org/extensions/xep-0204.html#ns'/>
<feature var='jabber:iq:register'/>
<feature var='jabber:iq:search'/>
<feature var='jabber:iq:time'/>
<feature var='jabber:iq:version'/>
</query>
</iq>
]]></example>
<example caption="When client A receives the response above, it will look for the value of the var attribute in feature"><![CDATA[
<feature var='http://www.xmpp.org/extensions/xep-0204.html#ns'/>
]]></example>
<example caption="If client A finds the value"><![CDATA[
http://www.xmpp.org/extensions/xep-0204.html#ns
]]></example>
<p>
it can assume the Client B supports the CDO protocol.
</p>
</section2>
<section2 topic="Query the Server to determine available CDO types" anchor="queryfortypes">
<p>
A CDO client can determine what types of CDOs are available by querying the server
</p>
<example caption="Client A constructs an IQ get and sends it to Server X"><![CDATA[
<iq type='get' from='joe@mitre.org/Desktop' id='cdo_list_1>
<query xmlns='http://www.xmpp.org/extensions/xep-0204.html#ns-types'/>
</iq>
]]></example>
<example caption="Server X responds with an IQ result listing the available CDO types"><![CDATA[
<iq type='result' to= id='joe@mitre.org/Desktop' cdo_list_1>
<query xmlns='http://www.xmpp.org/extensions/xep-0204.html#ns-types'>
<item id='1023'>
<name>Meeting CDO</name>
<description>Describes a meeting</description>
</item>
<item id='2001'>
<name>Trouble ticket</name>
<description>Describes a Trouble shooting ticket</description>
</item>
</query>
</iq>
]]></example>
<example caption="Client A selects the CDO type it would like to download by the item id"><![CDATA[
<iq type='get' from='joe@mitre.org/Desktop' id='cdo_list_2>
<query xmlns='http://www.xmpp.org/extensions/xep-0204.html#ns-types'>
<item id = '1023'/>
</query>
</iq>
]]></example>
<example caption="Server X responds with the selected CDO type. Returning the CDO description
language needed by the client"><![CDATA[
<iq type='result' to='joe@mitre.org/Desktop' id='cdo_list_2'>
<query xmlns='http://www.xmpp.org/extensions/xep-0204.html#ns-types'>
<cdo-dl>
...Actual CDO-DL definition
</cdo-dl>
</query>
</iq>
]]></example>
</section2>
<section2 topic="Query the Server to determine the state of a specific CDO" anchor="cdostate">
<p>
A CDO client can query the server to determine the specific state of a particular CDO:
</p>
<example caption="Client A constructs an IQ get and sends it to Server X wishing to obtain the current state of an existing CDO"><![CDATA[
<iq type='get' from='joe@mitre.org/Desktop' id='cdo_state_1>
<query xmlns='http://www.xmpp.org/extensions/xep-0204.html#ns-state'/>
<cdo uuid='ly8qoxl6r0rk42faell48a'/>
</query>
</iq>
]]></example>
<example caption="Server X responds with an IQ result showing the current state of the selected CDO."><![CDATA[
<iq type='result' to='joe@mitre.org/Desktop' id='cdo_state_1'>
<query xmlns='http://www.xmpp.org/extensions/xep-0204.html#ns-state'>
<data-sync protocol="1.0"
uuid="ly8qoxl6r0rk42faell48a"
type="cdo:Meeting"
packetID="0001"
event="info"
xmlns="http://www.xmpp.org/extensions/xep-0204.html#ns">
<item type="field"
uuid="kej3n4kd"
event="info"
ref="/Meeting/Attendees"
version="2">
<value>Bob, Jim, Mike, Added Dave</value>
</item>
</data-sync>
</query>
</iq>
]]></example>
<p>Note an event type of info. This requires all attributes for the data-sync element and items be present</p>
</section2>
<section2 topic="Query an endpoint for a list of CDOs" anchor="cdolist">
<p>In some cases a client may be interested in the state of all CDOs belonging to a specific endpoint - for example a chat room.</p>
<example caption="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[
<iq type='get' from='joe@mitre.org/Desktop' to='cdo_users@mitre.org' id='cdo_state_2>
<query xmlns='http://www.xmpp.org/extensions/xep-0204.html#ns-state'>
<cdo uuid='*'/>
</query>
</iq>
]]></example>
<example caption="Server X responds with an IQ result listing all current CDOs belonging to the CDO users chatroom"><![CDATA[
<iq type='result' to='joe@mitre.org/Desktop' id='cdo_state_2'>
<query xmlns='http://www.xmpp.org/extensions/xep-0204.html#ns-state'>
<data-sync protocol="1.0"
uuid="ly8qoxl6r0rk42faell48a"
type="cdo:Meeting"
event="info"
xmlns="http://www.xmpp.org/extensions/xep-0204.html#ns"/>
<data-sync protocol="1.0"
uuid="9sdfs454jh5"
type="cdo:Location"
event="info"
xmlns="http://www.xmpp.org/extensions/xep-0204.html#ns"/>
...
</query>
</iq>
]]></example>
<p>Note the value of the uuid for the cdo tag above uses an asterisk (*) to indicate all CDOs</p>
<p>
If desired, Client A can then query the Server for the details on the state of a specific CDO using the protocol described earlier.
</p>
</section2>
<section2 topic="Create a new CDO" anchor="cdocreate">
<p>When two endpoints (client A and client B) wish to create a new CDO. Each client and server MUST follow this algorithm:</p>
<example caption="Client A creates a new CDO and sends it to client B"><![CDATA[
<message
to='joe@mitre.org/Desktop'
from='bob@mitre.org/Laptop'
type='chat'
xml:lang='en'>
<data-sync protocol="1.0"
uuid=""
type="cdo:Meeting"
packetID="0001"
event="create"
xmlns="http://www.xmpp.org/extensions/xep-0204.html#ns">
<item type="field" uuid="" event="create" ref="/Meeting/Title" version="0">
<value>Technical Exchange Meeting</value>
</item>
</data-sync>
</message>
]]></example>
<p>Here client A, has created a packetID and set event=create in both &lt;data-sync&gt; and &lt;item&gt;. The version MUST be set to zero</p>
<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 &lt;data-sync&gt; and &lt;item&gt;. 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>
<example caption="Send receipt from Server X to client A"><![CDATA[
<message
to='joe@mitre.org/Desktop'
from='joe@mitre.org/Desktop'
type='chat'
xml:lang='en'>
<data-sync protocol="1.0"
uuid="ly8qoxl6r0rk42faell48a"
type="cdo:Meeting"
packetID="0001"
event="create"
xmlns="http://www.xmpp.org/extensions/xep-0204.html#ns">
<item type="field"
uuid="xdF10939"
event="create"
ref="/Meeting/Title"
version="1">
<value>Technical Exchange Meeting</value>
</item>
</data-sync>
</message>
]]></example>
<example caption="Forward the processed message from Server X to client B"><![CDATA[
<message
to='joe@mitre.org/Desktop'
from='bob@mitre.org/Laptop'
type='chat'
xml:lang='en'>
<data-sync protocol="1.0"
uuid="ly8qoxl6r0rk42faell48a"
type="cdo:Meeting"
packetID="0001"
event="create"
xmlns="http://www.xmpp.org/extensions/xep-0204.html#ns">
<item type="field"
uuid="xdF10939"
event="create"
ref="/Meeting/Title"
version="1">
<value>Technical Exchange Meeting</value>
</item>
</data-sync>
</message>
]]></example>
<p>Once this is completed, both clients have a synchronized CDO message with a uuid and a version number assigned by the server.</p>
</section2>
<section2 topic="Create a new Item on an existing CDO" anchor="cdoitemcreate">
<p>When client A wishes to create a new Item on an existing CDO, he sends the following information to client B</p>
<example caption="Client A creates a new item on an existing CDO and sends it to client B"><![CDATA[
<message
to='joe@mitre.org/Desktop'
from='bob@mitre.org/Laptop'
type='chat'
xml:lang='en'>
<data-sync protocol="1.0"
uuid="ly8qoxl6r0rk42faell48a"
type="cdo:Meeting"
packetID="0002"
event="update"
xmlns="http://www.xmpp.org/extensions/xep-0204.html#ns">
<item type="field" uuid="" event="create" ref="/Meeting/Title" version="0">
<value>Meeting</value>
</item>
</data-sync>
</message>
]]></example>
<p>
Here client A, has set event=update on the &lt;data-sync&gt; and event=create on the new &lt;item&gt;. 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 &lt;item&gt;
</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>
<example caption="Send receipt from Server X to client A"><![CDATA[
<message
to='joe@mitre.org/Desktop'
from='joe@mitre.org/Desktop'
type='chat'
xml:lang='en'>
<data-sync protocol="1.0"
uuid="ly8qoxl6r0rk42faell48a"
type="cdo:Meeting"
packetID="0002"
event="update"
xmlns="http://www.xmpp.org/extensions/xep-0204.html#ns">
<item type="field" uuid="kej3n4kd" event="create" ref="/Meeting/Title/" version="1">
<value>Meeting</value>
</item>
</data-sync>
</message>
]]></example>
<example caption="Forward the message from Server X to client B"><![CDATA[
<message
to='joe@mitre.org/Desktop'
from='bob@mitre.org/Laptop'
type='chat'
xml:lang='en'>
<data-sync protocol="1.0"
uuid="ly8qoxl6r0rk42faell48a"
type="cdo:Meeting"
packetID="0002"
event="update"
xmlns="http://www.xmpp.org/extensions/xep-0204.html#ns">
<item type="field" uuid="kej3n4kd" event="create" ref="/Meeting/Title/" version="1">
<value>Meeting</value>
</item>
</data-sync>
</message>
]]></example>
<p>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.</p>
</section2>
<section2 topic="Update an Item on an existing CDO" anchor="cdoitemupdate">
<p>When client A wishes to update an item on an existing CDO, he sends the following information to client B</p>
<example caption="Client A updates an item on an existing CDO and sends it to client B"><![CDATA[
<message
to='joe@mitre.org/Desktop'
from='bob@mitre.org/Laptop'
type='chat'
xml:lang='en'>
<data-sync protocol="1.0"
uuid="ly8qoxl6r0rk42faell48a"
type="cdo:Meeting"
packetID="0003"
event="update"
xmlns="http://www.xmpp.org/extensions/xep-0204.html#ns">
<item type="field"
uuid="kej3n4kd"
event="update"
version="1">
<value>2006-07-24T14:55:00</value>
</item>
</data-sync>
</message>
]]></example>
<p>
Here client A, has set event=update on the &lt;data-sync&gt; and event=update on the changed &lt;item&gt;. Note the version is set to the current
version being edited, in this case 1, and both the &lt;item&gt; and &lt;data-sync&gt; 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 &lt;item&gt;
</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>
<example caption="Send receipt from Server X to client A"><![CDATA[
<message
to='joe@mitre.org/Desktop'
from='joe@mitre.org/Desktop'
type='chat'
xml:lang='en'>
<data-sync protocol="1.0"
uuid="ly8qoxl6r0rk42faell48a"
type="cdo:Meeting"
packetID="0003"
event="update"
xmlns="http://www.xmpp.org/extensions/xep-0204.html#ns">
<item type="field"
uuid="kej3n4kd"
event="update"
version="2">
<value>2006-07-24T14:55:00</value>
</item>
</data-sync>
</message>
]]></example>
<example caption="Forward the message from Server X to client B"><![CDATA[
<message
to='joe@mitre.org/Desktop'
from='bob@mitre.org/Laptop'
type='chat'
xml:lang='en'>
<data-sync protocol="1.0"
uuid="ly8qoxl6r0rk42faell48a"
type="cdo:Meeting"
packetID="0003"
event="update"
xmlns="http://www.xmpp.org/extensions/xep-0204.html#ns">
<item type="field"
uuid="kej3n4kd"
event="update"
version="2">
<value>2006-07-24T14:55:00</value>
</item>
</data-sync>
</message>
]]></example>
<p>Once this is completed, both clients have a synchronized CDO message with an updated item. The updated item has the version number incremented.</p>
<section3 topic="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:
</p>
<code><![CDATA[
<data-sync protocol="1.0" uuid="cdo_1" packetID="0003"
event="update" xmlns="http://www.xmpp.org/extensions/xep-0204.html#ns">
<item type="field"
uuid="item_1"
event="update"
version="1"
updateStyle="inclusive">
<attribute name="attr_1">old value</attribute>
<attribute name="attr_2">new value</attribute>
</item>
</data-sync>
]]></code>
<code><![CDATA[
<data-sync protocol="1.0" uuid="cdo_1" packetID="0003"
event="update" xmlns="http://www.xmpp.org/extensions/xep-0204.html#ns">
<item type="field"
uuid="item_1"
event="update"
version="1"
updateStyle="exclusive">
<attribute name="attr_2">new value</attribute>
</item>
</data-sync>
]]></code>
</section3>
</section2>
<section2 topic="Delete an Item on an existing CDO" anchor="cdoitemdelete">
<p>When client A wishes to delete an item on an existing CDO, he sends the following information to client B</p>
<example caption="Client A deletes an item on an existing CDO and sends it to client B"><![CDATA[
<message
to='joe@mitre.org/Desktop'
from='bob@mitre.org/Laptop'
type='chat'
xml:lang='en'>
<data-sync protocol="1.0"
uuid="ly8qoxl6r0rk42faell48a"
type="cdo:Meeting"
packetID="0004"
event="update"
xmlns="http://www.xmpp.org/extensions/xep-0204.html#ns">
<item type="field"
uuid="kej3n4kd"
event="delete"
version="2">
</item>
</data-sync>
</message>
]]></example>
<p>
Here client A, has set event=update on the &lt;data-sync&gt; and event=delete on the changed &lt;item&gt;. Note the version is set to the current
version being deleted, in this case 2, and both the &lt;item&gt; and &lt;data-sync&gt; 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. 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>
<example caption="Send receipt from Server X to client A"><![CDATA[
<message
to='joe@mitre.org/Desktop'
from='joe@mitre.org/Desktop'
type='chat'
xml:lang='en'>
<data-sync protocol="1.0"
uuid="ly8qoxl6r0rk42faell48a"
type="cdo:Meeting"
packetID="0004"
event="update"
xmlns="http://www.xmpp.org/extensions/xep-0204.html#ns">
<item type="field"
uuid="kej3n4kd"
event="delete"
version="2">
</item>
</data-sync>
</message>
]]></example>
<example caption="Forward the message from Server X to client B"><![CDATA[
<message
to='joe@mitre.org/Desktop'
from='bob@mitre.org/Laptop'
type='chat'
xml:lang='en'>
<data-sync protocol="1.0"
uuid="ly8qoxl6r0rk42faell48a"
type="cdo:Meeting"
packetID="0004"
event="update"
xmlns="http://www.xmpp.org/extensions/xep-0204.html#ns">
<item type="field"
uuid="kej3n4kd"
event="delete"
version="2">
</item>
</data-sync>
</message>
]]></example>
<p>Once this is completed, both clients have a synchronized CDO message with a deleted item.</p>
</section2>
<section2 topic="Retire an existing CDO" anchor="cdoretire">
<p>
Retired objects are different than deleted items in that retired objects can still be referenced and reviewed but no changes can be made.
</p>
<p>
When client A wishes to retire an entire existing CDO, he sends the following information to client B
</p>
<example caption="Client A deletes an existing CDO and sends it to client B"><![CDATA[
<message
to='joe@mitre.org/Desktop'
from='bob@mitre.org/Laptop'
type='chat'
xml:lang='en'>
<data-sync protocol="1.0"
uuid="ly8qoxl6r0rk42faell48a"
type="cdo:Meeting"
packetID="0005"
event="retire"
xmlns="http://www.xmpp.org/extensions/xep-0204.html#ns">
</data-sync>
</message>
]]></example>
<p>
Here client A, has set event=retire on the &lt;data-sync&gt;.
</p>
<p>
The message is intercepted by Server X. Server X is the IM server that both clients are connected to. 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>
<example caption="Send receipt from Server X to client A"><![CDATA[
<message
to='joe@mitre.org/Descktop'
from='joe@mitre.org/Descktop'
type='chat'
xml:lang='en'>
<data-sync protocol="1.0"
uuid="ly8qoxl6r0rk42faell48a"
type="cdo:Meeting"
packetID="0005"
event="retire"
xmlns="http://www.xmpp.org/extensions/xep-0204.html#ns">
</data-sync>
</message>
]]></example>
<example caption="Forward the message from Server X to client B"><![CDATA[
<message
to='joe@mitre.org/Desktop'
from='bob@mitre.org/Laptop'
type='chat'
xml:lang='en'>
<data-sync protocol="1.0"
uuid="ly8qoxl6r0rk42faell48a"
type="cdo:Meeting"
packetID="0005"
event="retire"
xmlns="http://www.xmpp.org/extensions/xep-0204.html#ns">
</data-sync>
</message>
]]></example>
<p>Once this is completed, both clients have retired (deleted) the CDO.</p>
</section2>
</section1>
<section1 topic="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>
<example caption="Assume the following message is sent:"><![CDATA[
<message from="miles@example.com" to="aral@example.com">
<cdo:data-sync
protocol="1.0"
packetID="miles@example.com:packet-1"
event="update"
uuid="miles@example.com:instance-1">
<item type="field" event="create" ref="/Meeting/Title">
<value>Winterfair preparation</value>
</item>
<item type="field" event="update"
uuid="miles@example.com:field-1" version="2">
<value>Imperial waltz</value>
</item>
</cdo:data-sync>
</message>
]]></example>
<p>
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>
<example caption=""><![CDATA[
<message to="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"/>
<error type="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>
<example caption=""><![CDATA[
<message to="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">
<item type="field" event="update"
uuid="miles@example.com:field-1" version="2">
<value>Imperial waltz</value>
</item>
</cdo:data-sync>
<error type="cancel">
<item-not-found/>
<cdo:no-such-item/>
</error>
</message>
]]></example>
<section2 topic="CDO specific conditions" anchor="cdoerrorconditions">
<table caption="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>&lt;xmpp:feature-not-implemented/&gt;</tt>
</p>
</td>
<td>
<p>
<tt>&lt;cdo:unkown-protocol-version/&gt;</tt>
</p>
</td>
<td>
<p>The protocol version for the data sync packet is unknown to the framework and cannot be processed.</p>
</td>
</tr>
<tr>
<td>
<p>continue</p>
</td>
<td>
<p>
<tt>&lt;xmpp:undefined-condition/&gt;</tt>
</p>
</td>
<td>
<p>
<tt>&lt;cdo:deprecated-protocol-version framework-protocol-version="P"/&gt;</tt>
</p>
</td>
<td>
<p>The protocol version for the data sync packet is older than that used by the framework, but the packet can still be processed.</p>
</td>
</tr>
<tr>
<td>
<p>cancel</p>
</td>
<td>
<p>
<tt>&lt;xmpp:feature-not-implemented/&gt;</tt>
</p>
</td>
<td>
<p>
<tt>&lt;cdo:deprecated-protocol-version framework-protocol-version="P"/&gt;</tt>
</p>
</td>
<td>
<p>The protocol version for the data sync packet is older than that used by the framework, and the framework cannot process the packet.</p>
</td>
</tr>
<tr>
<td>
<p>continue</p>
</td>
<td>
<p>
<tt>&lt;xmpp:undefined-condition/&gt;</tt>
</p>
</td>
<td>
<p>
<tt>&lt;cdo:instance-identifier- conflict new-identifier="I"/&gt;</tt>
</p>
</td>
<td>
<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>&lt;xmpp:item-not-found/&gt;</tt>
</p>
</td>
<td>
<p>
<tt>&lt;cdo:no-such-instance/&gt;</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>&lt;xmpp:not-allowed/&gt;</tt>
</p>
</td>
<td>
<p>
<tt>&lt;cdo:instance-retired/&gt;</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>&lt;xmpp:undefined-condition/&gt;</tt>
</p>
</td>
<td>
<p>
<tt>&lt;cdo:instance-is-active/&gt;</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>&lt;xmpp:item-not-found/&gt;</tt>
</p>
</td>
<td>
<p>
<tt>&lt;cdo:no-such-type/&gt;</tt>
</p>
</td>
<td>
<p>The framework has no record of a type with the specified identifier.</p>
</td>
</tr>
<tr>
<td>
<p>continue</p>
</td>
<td>
<p>
<tt>&lt;xmpp:undefined-condition/&gt;</tt>
</p>
</td>
<td>
<p>
<tt>&lt;cdo:deprecated-type latest-type="type-identifier"/&gt;</tt>
</p>
</td>
<td>
<p>The framework will create a new instance with the specified type, but one or more types have been registered as superseding this type.</p>
</td>
</tr>
<tr>
<td>
<p>continue</p>
</td>
<td>
<p>
<tt>&lt;xmpp:undefined-condition/&gt;</tt>
</p>
</td>
<td>
<p>
<tt>&lt;cdo:item-identifier- conflict old-identifier="I0" new-identifier="I1"/&gt;</tt>
</p>
</td>
<td>
<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>&lt;xmpp:item-not-found/&gt;</tt>
</p>
</td>
<td>
<p>
<tt>&lt;cdo:no-such-item identifier="I"/&gt;</tt>
</p>
</td>
<td>
<p>The framework has no record of an item with the specified identifier for the specified instance.</p>
</td>
</tr>
<tr>
<td>
<p>cancel</p>
</td>
<td>
<p>
<tt>&lt;xmpp:conflict/&gt;</tt>
</p>
</td>
<td>
<p>
<tt>&lt;cdo:item-version-outdated identifier=I" version=V"/&gt;</tt>
</p>
</td>
<td>
<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>
</td>
</tr>
<tr>
<td>
<p>modify</p>
</td>
<td>
<p>
<tt>&lt;xmpp:bad-request/&gt;</tt>
</p>
</td>
<td>
<p>
<tt>&lt;cdo:no-such-item-version identifier="I" version="V"/&gt;</tt>
</p>
</td>
<td>
<p>The framework has no record of the specified version for the specified item. The framework MAY return the current version in the reply.</p>
</td>
</tr>
<tr>
<td>
<p>cancel</p>
</td>
<td>
<p>
<tt>&lt;xmpp:item-not-found/&gt;</tt>
</p>
</td>
<td>
<p>
<tt>&lt;cdo:no-such-item-xpath identifier="I"/&gt;</tt>
</p>
</td>
<td>
<p>The xpath in the specified identifier is not valid.</p>
</td>
</tr>
<tr>
<td>
<p>modify</p>
</td>
<td>
<p>
<tt>&lt;xmpp:not-acceptable/&gt;</tt>
</p>
</td>
<td>
<p>
<tt>&lt;cdo:item-xpath-not-acceptable identifier="I"/&gt;</tt>
</p>
</td>
<td>
<p>The xpath in the specified identifier does not resolve to a leaf element.</p>
</td>
</tr>
<tr>
<td>
<p>modify</p>
</td>
<td>
<p>
<tt>&lt;xmpp:not-acceptable/&gt;</tt>
</p>
</td>
<td>
<p>
<tt>&lt;cdo:item-modification-insufficient identifier="I"/&gt;</tt>
</p>
</td>
<td>
<p>The modification proposed on the item does not actually constitute a modification.</p>
</td>
</tr>
<tr>
<td>
<p>modify</p>
</td>
<td>
<p>
<tt>&lt;xmpp:bad-request/&gt;</tt>
</p>
</td>
<td>
<p>
<tt>&lt;cdo:invalid-item-value identifier="I"/&gt;</tt>
</p>
</td>
<td>
<p>The value proposed for the specified item is invalid.</p>
</td>
</tr>
<tr>
<td>
<p>cancel</p>
</td>
<td>
<p>
<tt>&lt;xmpp:item-not-found/&gt;</tt>
</p>
</td>
<td>
<p>
<tt>&lt;cdo:no-such-item-attribute identifier="I" attribute-name="N"/&gt;</tt>
</p>
</td>
<td>
<p>The item attribute in the specified identifier is invalid.</p>
</td>
</tr>
<tr>
<td>
<p>modify</p>
</td>
<td>
<p>
<tt>&lt;xmpp:bad-request/&gt;</tt>
</p>
</td>
<td>
<p>
<tt>&lt;cdo:invalid-item-value identifier="I" attribute-name="N"/&gt;</tt>
</p>
</td>
<td>
<p>The value proposed for the specified item's attribute is invalid.</p>
</td>
</tr>
<tr>
<td>
<p>modify</p>
</td>
<td>
<p>
<tt>&lt;xmpp:bad-request/&gt;</tt>
</p>
</td>
<td>
<p>
<tt>&lt;cdo:invalid-constraint type="T" identifier="I"/&gt;</tt>
</p>
</td>
<td>
<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>
</section2>
<section2 topic="Invalid Constraint condition types" anchor="invalidconstraints">
<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>
<table caption="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>
<section2 topic="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>
<p>The additional error information provide includes:</p>
<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>
</ul>
<example caption=""><![CDATA[
<cdo:item-version-outdated identifier='I' version='V'>
<cdo:conflict resource-identifier='R' execution-timestamp='T'>
<item identifier='I' version='V1' event='E'>
<value>VALUE</value>
<attribute name='N'>VALUE</attribute>
</cdo:conflict>
</cdo:item-version-outdated>
]]></example>
</section2>
</section1>
<section1 topic="Implementation Notes" anchor="impl">
<section2 topic="Service" anchor="service">
<p>
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>
<section2 topic="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 &lt;user@domain&gt;) or full JID (of the form &lt;user@domain/resource&gt;); otherwise, the client
SHOULD ignore the cdo query result.
</p>
</section2>
</section1>
<section1 topic="Security Considerations" anchor="security">
<section2 topic="User Authentication and Authorization" anchor="authentication">
<p>
No form of authentication or authorization is defined by this specification. However, if required, RFC 3920 describes channel encryption and
strong authentication via TLS and SASL that may fulfill this requirement.
</p>
</section2>
<section2 topic="End-to-End Encryption" anchor="encryption">
<p>
No end-to-end message or session encryption method defined in this specification. Users SHOULD NOT trust a service to exchange secret CDO messages.
</p>
</section2>
</section1>
<section1 topic="IANA Considerations" anchor="iana">
<p>This JEP requires no interaction with the Internet Assigned Numbers Authority (IANA).</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespace' anchor='ns'>
<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>
</section2>
</section1>
<section1 topic="XML Schema" anchor="schema">
<section2 topic="Description Language" anchor="xmlschemaDescriptionLanguage">
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xsd:schema
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:cdodl="http://mitre.org/MTP/CDO-DL"
targetNamespace="http://mitre.org/MTP/CDO-DL"
elementFormDefault="unqualified"
attributeFormDefault="unqualified">
<xsd:element name="Definition" type="cdodl:DefinitionType"/>
<xsd:complexType name="DefinitionType">
<xsd:sequence>
<xsd:element name="MetaData" minOccurs="1" maxOccurs="1">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Label" minOccurs="1" maxOccurs="1"/>
<xsd:element name="Version" minOccurs="1" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:pattern value="[1-9][0-9]*\.[0-9]+.[0-9]+.[0-9]+"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="Description" minOccurs="1" maxOccurs="1"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="Type" minOccurs="1" maxOccurs="1">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="xsd:schema" minOccurs="0" maxOccurs="1"/>
</xsd:sequence>
<xsd:attribute name="rootElement" use="required" type="xsd:QName"/>
<xsd:attribute name="schemaLocation" use="optional" type="xsd:anyURI"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="Layouts" minOccurs="1" maxOccurs="1">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Layout" minOccurs="1" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Description"
minOccurs="1"
maxOccurs="1"
type="xsd:string"/>
<any namespace="##other" minOccurs="1" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="default"
use="optional"
default="false"
type="xsd:boolean"/>
<xsd:attribute name="uuid" use="required" type="xsd:string"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="Methods" minOccurs="1" maxOccurs="1">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Method" minOccurs="1" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Description"
minOccurs="1"
maxOccurs="1"
type="xsd:string"/>
<any namespace="##other" minOccurs="1" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="uuid" use="required" type="xsd:string"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="States" minOccurs="1" maxOccurs="1">
<xsd:complexType>
<xsd:sequence>
<any namespace="##other" minOccurs="1" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="uuid" use="required" type="xsd:string"/>
</xsd:complexType>
</xsd:schema>
]]></code>
</section2>
<section2 topic="Data Synchronization Protocol" anchor="xmlschemaProtocol">
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:cdo="http://www.xmpp.org/extensions/xep-0204.html#ns-data-sync"
targetNamespace="http://www.xmpp.org/extensions/xep-0204.html#ns-data-sync"
elementFormDefault="unqualified"
attributeFormDefault="unqualified">
<xsd:element name="data-sync" type="cdo:DataSyncPacketType" />
<xsd:complexType name="DataSyncPacketType">
<xsd:sequence>
<xsd:element name="item"
type="cdo:DataSyncItemType"
minOccurs="0"
maxOccurs="unbounded" />
</xsd:sequence>
<xsd:attribute name="protocol" use="required">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:pattern value="[1-9][0-9]*\.[0-9]+" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="packetID" use="required" type="xsd:string" />
<xsd:attribute name="event" use="required">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="create" />
<xsd:enumeration value="update" />
<xsd:enumeration value="retire" />
<xsd:enumeration value="info" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="uuid" use="optional" type="xsd:string" />
<xsd:attribute name="type" use="optional" type="xsd:string" />
</xsd:complexType>
<xsd:complexType name="DataSyncItemType">
<xsd:sequence>
<xsd:element name="value" type="xsd:string" minOccurs="0" maxOccurs="1" />
<xsd:element name="attribute"
type="cdo:DataSyncAttributeType"
minOccurs="0"
maxOccurs="unbounded" />
</xsd:sequence>
<xsd:attribute name="type" use="optional" default="field">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="field" />
<xsd:enumeration value="method" />
<xsd:enumeration value="state" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="event" use="required">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="create" />
<xsd:enumeration value="update" />
<xsd:enumeration value="delete" />
<xsd:enumeration value="info" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="updateStyle" use="optional" default="exclusive">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="inclusive" />
<xsd:enumeration value="exclusive" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="uuid" use="optional" type="xsd:string" />
<xsd:attribute name="ref" use="optional">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:annotation>
<xsd:documentation xml:lang="en">
The pattern associated with this restriction
is intended to model a simple XPath statement
restricted only to element names. The included
regular expression is not fully representative
of all legal XML element names and should be
extended.
</xsd:documentation>
</xsd:annotation>
<xsd:pattern value="(/([a-zA-Z_][\w\.-_]*:)?[a-zA-Z_][\w\.-_]*)+" />
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="version" use="optional" type="xsd:positiveInteger" />
</xsd:complexType>
<xsd:complexType name="DataSyncAttributeType">
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:attribute name="name" type="xsd:QName" use="required" />
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:schema>
]]></code>
</section2>
</section1>
</xep>
Reference in New Issue View Git Blame Copy Permalink