WSDL and Schemas Discussion CMIS F2F January 27, 2009 Gary Gershon

Initial Review of SOAP Artifacts The 0.5 Schemas and WSDL artifacts are substantial working assets going into the OASIS TC process. From an initial review, various definition aspects were identified that: – Require change for broader tooling compatibility, – May hit platform implementation limitations, – Offer opportunities for simplification, and/or – Could be made more consistent. 1/27/092CMIS WSDL and Schemas

Tooling Obviously, the WSDL and Schema artifacts have been successfully consumed in multiple SOAP (SOA-Lite) environments for the prototype integration. However, they are not currently consumable by IBM’s WebSphere SOA platform tooling – WebSphere Integration Developer (WID) We need to arrange for tests using other SOA orchestration (BPM/BPEL) and ESB tools 1/27/093CMIS WSDL and Schemas

WebSphere Issues WebSphere’s WID product does holistic cross- schema and cross-WSDL analysis of all the artifacts in a project space. A particular schema element cannot be defined more than once in the same namespace. This behavior is consistent with best practices for SOAP. 1/27/094CMIS WSDL and Schemas

Duplicate-Definitions Solution Commonly solved by: – Using a separate namespace per Schema/WSDL file – Defining elements that are used in multiple services once and importing their definitions were needed Note that this issue is not restricted to WID. Standard Service Data Objects (SDOs) generate a factory class per artifact file using the namespace to define both the factory package and factory name. Having multiple schema files with the same namespace is a major problem with SDOs. 1/27/095CMIS WSDL and Schemas

Platform Adoption Issues Various vendor stacks absorb standards at different times. While MTOM has been available for several years as a potential replacement for SWA and DIME, it was only adopted for WebSphere Application Server (WAS) last year, and is not yet directly supported by WebSphere Process Server (WPS) or WebSphere ESB (WESB). Thus, MTOM is currently supported within the IBM stack for Point-to-Point services (SOA-Lite), but not for full mediated (ESB) or orchestrated (BPM/BPEL) SOA environments. 1/27/096CMIS WSDL and Schemas

MTOM Solutions One can develop an SOA SCA “Adapter” component for WESB that parses and assembles MTOM streams. CMIS could support multiple mechanisms to transfer the “content stream” via SOAP: – xsd:binhex64 – base-64 inline encoding of content within XML – Content-stream representation in SOAP message as a URL to a (temporary) persistence store 1/27/097CMIS WSDL and Schemas

Content Stream via binhex64 An Schema definition type of xsd:binhex64 will encode a byte array using base-64 character encoding Not as efficient as MTOM for large files Usually a good choice for small files since the content doesn’t need to be written to a temporary file and accessed later from secondary storage when needed 1/27/098CMIS WSDL and Schemas

Content Steams via URL (within SOAP) Supporting a URL reference within the SOAP message is a powerful option – It allows the message to be very small. – It provides a crisp transformed-message option when stripping off the MTOM attachments. – It is consistent with HTML/XHTML whereby all content files are referenced by URLs within XML. – It is consistent with WebDAV where various methods (e.g. PROPFIND) return XML including document URLs URLs within SOAP should be available for both sets and gets of Content Streams. 1/27/099CMIS WSDL and Schemas

A Content Stream Side-Issue The name “Content Stream” is an overload of the C/Java/.Net/Unix concept of a “stream” Most developers expect a stream object to support APIs like read, write, close, mark/reset Could we call the bytes simply “Content” and have CMIS services support “getContent” and “setContent” operations? Then a program could open a stream on the Content to process the document, and we could refer to the ContentSize and the ContentType… 1/27/09CMIS WSDL and Schemas10

Other WSDL Issues If other transports beyond HTTP are to be eventually supported, then each WSDL file should be split into two files: – Base file with interface – Transport binding file for each protocol (e.g. one for HTTP and another for JMS) – The binding file references the first file (includes). – As new protocols are added, the first file containing the interface definition does not change. 1/27/0911CMIS WSDL and Schemas

Schema Issues Too many modeled faults Opportunity to simplify properties Recommend against use of “qualified” Opportunity for collections of objects Naming- and construction-consistency opportunities 1/27/0912CMIS WSDL and Schemas

Fault Simplification Modeled WSDL (SOAP) faults were designed to provide a mechanism to return specific structured data elements to the invoker. There is no need to have multiple faults returning the same structure. Major persistence and messaging frameworks have only one primary Exception (Fault) message, such as SQL, MQ, etc. Recommend adopting a single ContentManagement fault to replace the current multiple faults. This new fault would contain a “type code” to indicate the cause. This would substantially simplify consumer programming by reducing the number of “catch” structures for these faults. The 0.5 draft calls these “Exceptions” – but they are actually SOAP or WSDL “Faults” (which perhaps resulted from a.NET or Java Exception). 1/27/0913CMIS WSDL and Schemas

Properties Opportunities Properties – Simplify duplicate strongly typed elements. – Eliminate (apparently) redundant sequencing index attribute. – Eliminate confusing multiple-typed Value element. – Need to clarify when strong-typing is required or is simply optional. – Eliminate duplicate cmisPropertyType attribute when element name is already strongly typed – Define additional standard optional properties (MD5) 1/27/0914CMIS WSDL and Schemas

Property Definition Example 0.5 <xs:attribute ref="cmis:propertyType" use="optional" default="boolean" /> <xs:attribute ref="cmis:propertyType" use="optional" default="integer" /> 1/27/09CMIS WSDL and Schemas15

Can we simplify all this? Simplified XSD: Example: /27/09CMIS WSDL and Schemas16

Qualified in XSD Specifying elementFormDefault="qualified” causes all message elements to be prefixed with a namespace id “ vs. This adds substantial bulk to the messages and reduces readability. There are various academic arguments for prefixing every element, but few practical examples. By observation, the WebSphere integration tools do not use qualified elements by default, nor do they provide an UI option to turn on qualified. 1/27/0917CMIS WSDL and Schemas

Collections of Objects Using collections as service arguments avoids repetitious service requests. Generally implementing collections is a simple programming task to perform iterations. Recommend we support more collections of request arguments to support batches of objects being stored or retrieved via capture systems or as parts of compound documents (e.g. setContent operation with multiple independent Content Streams) Enlarged unit-of-work semantics would need to be discussed. 1/27/0918CMIS WSDL and Schemas

Consistency Opportunities Files and enumerations do not use upper-, lower-, and upper/lower camel-case and separators (dashes) consistently Schemas do not make consistent (or effective) use of default values (e.g. minOccurs=1 and maxOccurs=1) We should revisit “nillable” to see if usages are appropriate given the added complexity: – <xs:element name="filter" type="xs:string" minOccurs="0" – maxOccurs="1" nillable="true" /> – Here filter is an optional XML element. Do we actually need to differentiate an empty string value from filter having a “null” value : since the entire element can be omitted if not needed. 1/27/0919CMIS WSDL and Schemas

Next Steps Have discussions to better understand considerations used in original 0.5 spec. Need small WSDL and Schemas working group to provide recommendations for the larger TC committee. 1/27/0920CMIS WSDL and Schemas