Collaborative Data Objects

%ents; ]>

Collaborative Data Objects This document specifies an XMPP protocol extension that supports the exchange of structured data objects. &LEGALNOTICE; 0204 Deferred Standards Track Standards Council XMPP Core TO BE ISSUED Dave Bryson dbryson@mitre.org Dan Winkowski winkowsk@mitre.org Michael Krutsch michael@mitre.org Chad Smith chadsm@mitre.org Jasen Jacobsen jasenj1@mitre.org Marshall Huss mhuss@mitre.org 0.1 2007-01-17 psa

Initial published version; modified namespaces to adhere to XSF policy.

0.0.3 2006-12-29 mwh

Converting to validate against new XEP schema

0.0.2 2006-09-15 deb

Edits, some reformating, Spell check

0.0.1 2006-08-30 deb

First draft.

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:

Determine the ability for clients and servers to support and exchange collaborative data objects
Enable the exchange of structured data objects between clients
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 lazy synchronization model that may relax the current approach.
Operate in both private and group chat

Future enhancements may provide the ability to:

Query room for active CDOs
Query room history - results in CDO events for playback (per CDO or for all CDOs)
Register methods to a CDO
Register synchronization preference with framework (strict, lazy) CDO
Method invocation request to framework to execute and return response

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:

Client A 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.
Client A sends the meeting information to client B over normal chat.
When client A adds, updates, or deletes an item on the meeting, the changes are reflected to Client B
Similarily, when client B adds, updates, or deletes an item on the meeting, the changes are reflected to Client A

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.

Client A wishes to send information about a new meeting to client B
Client A first sends an IQ packet to client B to determine if the client supports the CDO protocol.
Client B responds to the IQ packet from client A confirming that it does support the CDO protocol.
Client A creates a new meeting that contains structured data such as the title of the meeting and the location.
When client A sends the CDO to client B, the message is intercepted by server X.
Server X, examines the message from client A and determines that it is a CDO create message. The server increments the version of the meeting items and forwards the message to client B.
When client A adds, updates, or deletes an item on the meeting, the changes are first interrogated by server X and then forwarded to Client B
Similarily, When client B adds, updates, or deletes an item on the meeting, the changes are first interrogated by server X and then forwarded to Client A
After processing the message from Client A, Server X will return a receipt to Client A. The receipt contains the UUID for the new item along with confirming the event was valid.

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:

UUID: 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.
Label: 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.
Version: 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.
Description: A more complete description of the data and context of a type. A description can exist for individual languages.
Schema: 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.

Beyond this core data, every CDO-DL can have multiple (but equivalent) standard-specific implementations for the remaining context of the type:

Layout: 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.
Method: 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.
State: 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).

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.

This is a new meeting ]]>

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

This is a new meeting ]]>

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.

28 May 2006 ]]>

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;.

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

]]> ]]> ]]>

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

]]> Meeting CDO Describes a meeting Trouble ticket Describes a Trouble shooting ticket ]]> ]]>

...Actual CDO-DL definition

]]>

A CDO client can query the server to determine the specific state of a particular CDO:

]]>

Bob, Jim, Mike, Added Dave

]]>

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.

]]>

...

]]>

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:

Technical Exchange Meeting ]]>

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

Technical Exchange Meeting ]]> Technical Exchange Meeting ]]>

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

Meeting ]]>

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

Meeting ]]> Meeting ]]>

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

2006-07-24T14:55:00 ]]>

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

2006-07-24T14:55:00 ]]> 2006-07-24T14:55:00 ]]>

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:


  
    old value
    new value
  

]]>


  
       new value
  

]]>

When client A wishes to delete an item on an existing CDO, he sends the following information to client B

]]>

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

]]> ]]>

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

]]>

Here client A, has set event=retire on the <data-sync>.

]]> ]]>

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.

Winterfair preparation Imperial waltz ]]>

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.

]]>

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.

Imperial waltz

]]>

Error Type	General Condition	Specific Condition	Description
cancel	`<xmpp:feature-not-implemented/>`	`<cdo:unkown-protocol-version/>`	The protocol version for the data sync packet is unknown to the framework and cannot be processed.
continue	`<xmpp:undefined-condition/>`	`<cdo:deprecated-protocol-version framework-protocol-version="P"/>`	The protocol version for the data sync packet is older than that used by the framework, but the packet can still be processed.
cancel	`<xmpp:feature-not-implemented/>`	`<cdo:deprecated-protocol-version framework-protocol-version="P"/>`	The protocol version for the data sync packet is older than that used by the framework, and the framework cannot process the packet.
continue	`<xmpp:undefined-condition/>`	`<cdo:instance-identifier- conflict new-identifier="I"/>`	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	`<xmpp:item-not-found/>`	`<cdo:no-such-instance/>`	The framework has no record of an instance with the specified identifier.
cancel	`<xmpp:not-allowed/>`	`<cdo:instance-retired/>`	The event cannot be executed on the instance because that instance has been retired.
wait	`<xmpp:undefined-condition/>`	`<cdo:instance-is-active/>`	The retire event cannot be executed on the instance because the instance is actively being updated.
cancel	`<xmpp:item-not-found/>`	`<cdo:no-such-type/>`	The framework has no record of a type with the specified identifier.
continue	`<xmpp:undefined-condition/>`	`<cdo:deprecated-type latest-type="type-identifier"/>`	The framework will create a new instance with the specified type, but one or more types have been registered as superseding this type.
continue	`<xmpp:undefined-condition/>`	`<cdo:item-identifier- conflict old-identifier="I0" new-identifier="I1"/>`	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	`<xmpp:item-not-found/>`	`<cdo:no-such-item identifier="I"/>`	The framework has no record of an item with the specified identifier for the specified instance.
cancel	`<xmpp:conflict/>`	`<cdo:item-version-outdated identifier=I" version=V"/>`	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	`<xmpp:bad-request/>`	`<cdo:no-such-item-version identifier="I" version="V"/>`	The framework has no record of the specified version for the specified item. The framework MAY return the current version in the reply.
cancel	`<xmpp:item-not-found/>`	`<cdo:no-such-item-xpath identifier="I"/>`	The xpath in the specified identifier is not valid.
modify	`<xmpp:not-acceptable/>`	`<cdo:item-xpath-not-acceptable identifier="I"/>`	The xpath in the specified identifier does not resolve to a leaf element.
modify	`<xmpp:not-acceptable/>`	`<cdo:item-modification-insufficient identifier="I"/>`	The modification proposed on the item does not actually constitute a modification.
modify	`<xmpp:bad-request/>`	`<cdo:invalid-item-value identifier="I"/>`	The value proposed for the specified item is invalid.
cancel	`<xmpp:item-not-found/>`	`<cdo:no-such-item-attribute identifier="I" attribute-name="N"/>`	The item attribute in the specified identifier is invalid.
modify	`<xmpp:bad-request/>`	`<cdo:invalid-item-value identifier="I" attribute-name="N"/>`	The value proposed for the specified item's attribute is invalid.
modify	`<xmpp:bad-request/>`	`<cdo:invalid-constraint type="T" identifier="I"/>`	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:

The resource identifier of the client originating the data sync packet with which this error conflicts.
The timestamp of when the originating data sync packet was executed.
The item element of the originating data sync packet with which this error conflicts.

VALUE VALUE ]]>

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:

Filter for data-sync and IQ protocol extentions as described above
Handle packet extentions that appear as a child element to the message element
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.

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:

Filter and respond to data-sync and IQ protocol extentions described in this specification
Properly handle packet extentions that appear as a child elements to the message element
Provide an underlying framework that can manage the version of data-sync messages. (see 3. above)
Provide a form based GUI to properly construct the CDO messages.
Provide the ability to construct data-sync related IQ messages

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 &xep0053;.

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.

]]>



  
  
  
    
  
  
   
    
     
    
   
  
  
  
    
      
       
       
       
       
      
     
  
  
  
  
  
   
     
     
   
   
     
      
       
       
       
      
     
   
   
     
      
       
       
       
       
      
     
  
  
   
     
      
      
     
   
  
  
  
    
      
        
        
            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.
        
       
       
     
    
  
  
  
  
    
     
      
     
   
 

]]>