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 strict synchronization model. In a strict synchronization model, participants will receive every change made to a CDO. An alternative synchronization model, a lazy synchronization 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.
This JEP describes a protocol that is designed to fulfill the following requirements:
Future enhancements may provide the ability to:
Here is a high-level description of the flow between two clients exchanging information using the CDO protocol.
Participants using strict synchronization will receive every change event to the CDOs in a room or private chat.
Imagine two chat clients, A and B,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.
For example, let's assume the clients wish to coordinate a meeting over chat. The process may look like this:
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 X). Server X is the IM server that both client A and B are connected to.
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).
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.
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.
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.
Some information is required for every CDO-DL to maintain consistent interpretation:
Beyond this core data, every CDO-DL can have multiple (but equivalent) standard-specific implementations for the remaining context of the type:
The CDO protocol uses the namespace: http://www.xmpp.org/extensions/xep-0204.html#ns
<data-sync/> is the root element and MUST be contained within a message stanza <message/> element. When the <data-sync> element is present in the <message>,the message MUST not contain a <body> element.
<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>
The <data-sync> element may contain <item> elements.The attributes of the <data-sync> element maintain high-level information about the enclosed <item> elements to help synchronize information exchanged between clients.
| Attribute | Description | Mandatory? |
| protocol | The version of the CDO exchange protocol | Yes |
| uuid | A universal unique identification number | Yes |
| packetID | 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. | Yes |
| type | the uuid of the CDO definition (CDO-DL) | mandatory on create event and info event, otherwise forbidden |
| event | cdo event type: create, update, retire, info | Yes |
|
Attribute |
Description |
Mandatory? |
|
uuid |
assigned ID of the field instance at creation time |
Yes |
|
type |
distinguishes the type of field (allowed children may vary) |
No |
|
ref |
xpath reference to the element |
mandatory on create event and info event, otherwise forbidden |
|
event |
identified action on the item: create, update, delete, and info with update as default |
Yes |
|
version |
integer version number of item being changed |
Yes |
|
updateStyle |
indicates inclusive or exclusive update style with exclusive as the default |
No |
Each <item> may contain:
0 or 1 (0..1) <value> elements with content corresponding to the change to the identified CDO instance element contents
<item type="field" uuid="" event="create" ref="/Meeting/Title" version="0"> <value>This is a new meeting</value> </item>
0 or unbounded (0..*) <attribute> 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.
<item type="field" uuid="" event="create" ref="/Meeting/Time/Start" version="0"> <attribute name="date">28 May 2006</attribute> </item>
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 Service Discovery (XEP-0030) [1].
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
<iq type='get'from='joe@mitre.org/Desktop' to='bob.mitre.org/Laptop'> <query xmlns='http://jabber.org/protocol/disco#info'/> </iq>
<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>
<feature var='http://www.xmpp.org/extensions/xep-0204.html#ns'/>
http://www.xmpp.org/extensions/xep-0204.html#ns
it can assume the Client B supports the CDO protocol.
A CDO client can determine what types of CDOs are available by querying the server
<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>
<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>
<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>
<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>
A CDO client can query the server to determine the specific state of a particular CDO:
<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>
<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>
Note an event type of info. This requires all attributes for the data-sync element and items be present
In some cases a client may be interested in the state of all CDOs belonging to a specific endpoint - for example a chat room.
<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>
<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>
Note the value of the uuid for the cdo tag above uses an asterisk (*) to indicate all CDOs
If desired, Client A can then query the Server for the details on the state of a specific CDO using the protocol described earlier.
When two endpoints (client A and client B) wish to create a new CDO. Each client and server MUST follow this algorithm:
<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>
Here client A, has created a packetID and set event=create in both <data-sync> and <item>. The version MUST be set to zero
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
<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>
<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>
Once this is completed, both clients have a synchronized CDO message with a uuid and a version number assigned by the server.
When client A wishes to create a new Item on an existing CDO, he sends the following information to client B
<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>
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>
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
<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>
<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>
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.
When client A wishes to update an item on an existing CDO, he sends the following information to client B
<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>
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.
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>
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
<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>
<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>
Once this is completed, both clients have a synchronized CDO message with an updated item. The updated item has the version number incremented.
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.
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:
<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>
<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>
When client A wishes to delete an item on an existing CDO, he sends the following information to client B
<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>
Here client A, has set event=update on the <data-sync> and event=delete on the changed <item>. Note the version is set to the current version being deleted, in this case 2, and both the <item> and <data-sync> have an existing uuid.
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
<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>
<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>
Once this is completed, both clients have a synchronized CDO message with a deleted item.
Retired objects are different than deleted items in that retired objects can still be referenced and reviewed but no changes can be made.
When client A wishes to retire an entire existing CDO, he sends the following information to client B
<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>
Here client A, has set event=retire on the <data-sync>.
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:
<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>
<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>
Once this is completed, both clients have retired (deleted) the CDO.
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.
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.
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.
<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>
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 MUST include the data-sync element to provide context; a bandwidth-constrainted connection MAY omit the element descendants.
<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>
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.
<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>
|
Error Type |
General Condition |
Specific Condition |
Description |
|
cancel |
|
|
The protocol version for the data sync packet is unknown to the framework and cannot be processed. |
|
continue |
|
|
The protocol version for the data sync packet is older than that used by the framework, but the packet can still be processed. |
|
cancel |
|
|
The protocol version for the data sync packet is older than that used by the framework, and the framework cannot process the packet. |
|
continue |
|
|
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. |
|
cancel |
|
|
The framework has no record of an instance with the specified identifier. |
|
cancel |
|
|
The event cannot be executed on the instance because that instance has been retired. |
|
wait |
|
|
The retire event cannot be executed on the instance because the instance is actively being updated. |
|
cancel |
|
|
The framework has no record of a type with the specified identifier. |
|
continue |
|
|
The framework will create a new instance with the specified type, but one or more types have been registered as superseding this type. |
|
continue |
|
|
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. |
|
cancel |
|
|
The framework has no record of an item with the specified identifier for the specified instance. |
|
cancel |
|
|
The request cannot be executed on the item because the referenced version is outdated. The framework MAY indicate the current version in the reply. |
|
modify |
|
|
The framework has no record of the specified version for the specified item. The framework MAY return the current version in the reply. |
|
cancel |
|
|
The xpath in the specified identifier is not valid. |
|
modify |
|
|
The xpath in the specified identifier does not resolve to a leaf element. |
|
modify |
|
|
The modification proposed on the item does not actually constitute a modification. |
|
modify |
|
|
The value proposed for the specified item is invalid. |
|
cancel |
|
|
The item attribute in the specified identifier is invalid. |
|
modify |
|
|
The value proposed for the specified item's attribute is invalid. |
|
modify |
|
|
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. |
Errors which may result from schema validation have been omitted.
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:
|
Type |
Description |
|
instance-identifier-required |
Data-sync packets of event type "update" and "retire" MUST specify the target instance. |
|
instance-type-prohibited |
Data-sync packets of event type "update" and "retire" MUST NOT specify an instance type. |
|
instance-type-required |
Data-sync packets of event type "create" MUST specify an instance type. |
|
item-required |
Data-sync packets of event type "update" MUST include at least one data-sync item. |
|
items-prohibited |
Data-sync packets of event type "retire" MUST NOT include any data-sync items. |
|
item-event-prohibited |
Data-sync packets of event type "create" MUST ONLY include data-sync items of event type "create." |
|
item-identifier-required |
Data-sync items of event type "update" and "delete" MUST include the target identifier. |
|
item-update-style-prohibited |
Data-sync items of event type "create" and "delete" MUST NOT specify an update style. |
|
item-value-prohibited |
Data-sync items of event type "delete" MUST NOT contain a value. |
|
item-value-required |
Data-sync items of event type "create" and "update" MUST contain a value. |
|
item-version-prohibited |
Data-sync items of event type "create" MUST NOT specify a version. |
|
item-version-required |
Data-sync items of event type "update" and "delete" MUST specify a version. |
|
item-xpath-prohibited |
Data-sync items of event type "update" and "delete" MUST NOT specify an XPath. |
|
item-xpath-required |
Data-sync items of event type "create" MUST specify an XPath. |
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.
The additional error information provide includes:
<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>
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:
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.
For a client to be able to exchange CDO messages it will need to provide capabilites similar to those described above:
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 SHOULD ignore the cdo query result.
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.
No end-to-end message or session encryption method defined in this specification. Users SHOULD NOT trust a service to exchange secret CDO messages.
This JEP requires no interaction with the Internet Assigned Numbers Authority (IANA).
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 XMPP Registrar Function (XEP-0053) [2].
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.
<?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>
<?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>
This document in other formats: XML PDF
This XMPP Extension Protocol is copyright © 1999 – 2020 by the XMPP Standards Foundation (XSF).
Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.
## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##
In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.
This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <https://xmpp.org/about/xsf/ipr-policy> or obtained by writing to XMPP Standards Foundation, P.O. Box 787, Parker, CO 80134 USA).
The HTML representation (you are looking at) is maintained by the XSF. It is based on the YAML CSS Framework, which is licensed under the terms of the CC-BY-SA 2.0 license.
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.
The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.
Discussion on other xmpp.org discussion lists might also be appropriate; see <http://xmpp.org/about/discuss.shtml> for a complete list.
Errata can be sent to <editor@xmpp.org>.
The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".
1. XEP-0030: Service Discovery <https://xmpp.org/extensions/xep-0030.html>.
2. XEP-0053: XMPP Registrar Function <https://xmpp.org/extensions/xep-0053.html>.
Note: Older versions of this specification might be available at http://xmpp.org/extensions/attic/
Initial published version; modified namespaces to adhere to XSF policy.
Converting to validate against new XEP schema
Edits, some reformating, Spell check
First draft.
END