Clarification on SOAP Array

Table of Contents

• A common user error when defining SOAP Array in WSDL
• ActiveMatrix BusinessWorks does not produce SOAP messages with xsi:type="soapenc:Array" on the SOAP Array element
• SOAP Array used in RPC/literal (or Document/literal) bindings
• Information to be sent to TIBCO Support

SOAP Array is one of the few features in the legacy SOAP Encoding standard that is still commonly used today. In general, a SOAP message with SOAP Array cannot be processed with a standard XML processor and therefore many interoperability issues arise around messages with SOAP Array. In this article, we provide some understanding of the concept and mention some common interoperability issues.

SOAP Array was first defined in the SOAP 1.1 specification, Section 5. Section 5 defines SOAP Encoding, which is an encoding style based on a simple type system.

When using WSDL to describe a SOAP interface, use "encoded" binding to choose an encoding style other than literally applying XSD schema. In most cases, SOAP Encoding is chosen as the encoding style by setting encodingStyle="http://schemas.xmlsoap.org/soap/encoding/". Additionally, since "encoded" binding always comes with RPC style, SOAP Array is traditionally used with RPC-encoded bindings.

In WSDL and SOAP messages, the "http://schemas.xmlsoap.org/soap/encoding/" namespace is commonly associated with "soapenc" as prefix; therefore, SOAP Array is normally noted as "soapenc:Array".

A common user error when defining SOAP Array in WSDL

Please refer to the following snippet from the XML Schema specification :

This means the type definition "ArrayOfSomeCustomType", which is derived by restriction from "soapenc:Array" and repeats no component in "soapenc:Array" definition except for the "soapenc:arrayType" attribute, allows no element content! In another word, such definition defines an empty array in the SOAP message.

We realize there are some WSDL samples on the internet with the above definition, which is why, like some other SOAP engines, the TIBCO ActiveMatrix BusinessWorks? SOAP engine actually tries to compensate for this user error. In many cases, ActiveMatrix BusinessWorks will interpret the above definition as a SOAP Array with items of a "SomeCustomType" type. However, because such a user error does not come with a specification, it is not possible to guarantee that ActiveMatrix BusinessWorks can compensate for the error in all scenarios (or compensate for it in the same way other SOAP engines do).

Therefore, it is always better to define a SOAP Array correctly as per the following example:

ActiveMatrix BusinessWorks does not produce SOAP messages with xsi:type="soapenc:Array" on the SOAP Array element

Given the above WSDL definition, some SOAP engines would generate the following SOAP Array within a SOAP message:

   bar 

Note that the declaration

 xsi:type="soapenc:Array"

is invalid according to the XML Schema specification. Please refer to the specification section 3.3.4 (Element Declaration Validation Rules), rule #4, and specifically rule #4.3 (see below):

4.3 The local type definition must be validly derived from the {type definition} given the union of the{disallowed substitutions} and the {type definition}'s {prohibited substitutions}, as defined in Type Derivation OK (Complex)(�§3.4.6) (if it is a complex type definition), or given {disallowed substitutions} as defined in Type Derivation OK (Simple)(�§3.14.6) (if it is a simple type definition).

In short, the value of the "xsi:type" attribute must be a derived type of the element type defined in the schema, which is "ArrayOfSomeCustomType" and this is clearly not the case, because "ArrayOfSomeCustomType" is a derived type of "soapenc:Array" but "soapenc:Array" is not a derived type of "ArrayOfSomeCustomType".

The reason for SOAP engines to generate such SOAP message is that the SOAP (and SOAP Encoding) standard predates WSDL and XML Schema standards. At the time, SOAP engines did not use the XML Schema (XSD) "bind" SOAP messages and so for a SOAP Array element like "foo", "xsi:type" was always set to "soapenc:Array".

Since XSD schema and WSDL became standards, the industry has moved away from this convention and adopted XSD schema to process SOAP Array as much as possible. Therefore, "xsi:type" has to be set according to the schema definition which in our case should be "ArrayOfSomeCustomType".

ActiveMatrix BusinessWorks understands the old industry convention and actually accepts SOAP messages in both forms; however, it only generates SOAP messages with "xsi:type" set according to the XML Schema definition which is the current industry convention. This sometimes causes interoperability issues when communicating SOAP Array with very old SOAP engines. In order to overcome such issues, the workaround would be to set up a proxy between ActiveMatrix BusinessWorks and the old SOAP engine to convert "xsi:type" from the type defined in the XML Schema (i.e. "ArrayOfSomeCustomType") to "soaped:Array".

SOAP Array used in RPC/literal (or Document/literal) bindings

Although SOAP Array was first defined for RPC-encoded binding, there is an industry-standard schema associated with soap encoding rules (see http://schemas.xmlsoap.org/soap/encoding/).

Here you see SOAP Array defined in a normal schema. Remember that to process SOAP Array in RPC-encoded binding, the SOAP engine has to implement special rules in addition to, or different from, the normal schema validation rules. If not, multi-dimensional arrays, for instance, cannot be processed. For example, the definition of "ArrayOfSomeCustomType" above allows a sequence of elements of "SomeCustomType" type which in general, doesn't allow sub-element of "SomeCustomType" type, hence it doesn't allow two dimensional array by the schema definition.

However when you set 'use="literal"', the SOAP engine has to process SOAP Array strictly according to the schema definitions.

Information to be sent to TIBCO Support

If ActiveMatrix BusinessWorks is unable to process a SOAP message generated from another SOAP engine, please open a Support Request (SR) with TIBCO Support and provide the following:

• Create a simplified project that demonstrates the problem. In most cases, a Process with SOAPEventSource or Service resource with an "empty" process to implement the operation should demonstrate the problem.
• Capture and upload the SOAP message sent from the other SOAP engine.
• Include any error message received in the ActiveMatrix BusinessWorks logs.

If another SOAP engine is unable to process a SOAP message generated from ActiveMatrix BusinessWorks, open a SR with the following:

• Likewise before, create a simplified project that demonstrates the problem. In most cases, a Process with SOAP Request/Reply or Invoke Partner can demonstrate the problem.
• Capture and upload the SOAP message sent from ActiveMatrix BusinessWorks.
• Provide the SOAP message generated with the same WSDL that the other SOAP engine accepts.
• Include any error message received in the ActiveMatrix BusinessWorks logs.

To capture SOAP messages sent to or from ActiveMatrix BusinessWorks, you can either use a third party tool like "tcpmon.jar" to intercept the message, or use SOAP tracing in ActiveMatrix BusinessWorks. To enable SOAP tracing, add the following properties to the applicable ".tra" file:

 java.property.com.tibco.plugin.soap.trace.inbound=true java.property.com.tibco.plugin.soap.trace.outbound=true java.property.com.tibco.plugin.soap.trace.filename=c:/temp/soap.txt java.property.com.tibco.plugin.soap.trace.pretty=true java.property.com.tibco.plugin.soap.trace.stdout=true

Please make sure the file referred to by "java.property.com.tibco.plugin.soap.trace.filename" does exist before you start the test.

[Note: you must restart the ActiveMatrix BusinessWorks engine or Designer in order for the tracing properties above to take effect.