Fpml Root Element Options

FpML Root Element Options

1. Purpose

This paper discusses issues related to the design of the FpML root element and considers options for addressing these issues.

2. Background

2.1. Existing Situation

Currently, all FpML documents have a root element called “FpML”. This element has a required version attribute called “version” which denotes the FpML version in major-minor (e.g. 4-2) format. In addition, the xsi:type attribute (in the XML Schema-Instance namespace) is used to specify the content model of the FpML document, which is either DataDocument or a specific message type.

Several concerns have been raised about this model, including:

· The use of xsi:type is unfamiliar or confusing to many people who are new to XML or XML Schema

· Xsi:type is not well supported by certain tools and/or standards

· The use of a single root element (FpML) may cause problems in integration with other standards.

· This approach is not in line with approaches used in other standards.

2.2. Issues

The following issues have been reported on the FpML issues list related to this point:

· #190 - http://www.fpml.org/issues/view.php?id=190 Altova Mapforce does not support xsi:type

· #219 - http://www.fpml.org/issues/view.php?id=219 WSDL does not support xsi:type in root node (this issue superseded by #249, immediately below)

· #249 - http://www.fpml.org/issues/view.php?id=249 W3C WSDL group advises distinct root elements per message.

The first issue is a specific tool support issue with xsi:type. The second and third issues relate to the difficulty of integrating WSDL 2.0 with the existing FpML root element model. As quoted in issue #249, the WS Description Working Group refused to make changes to WSDL 2.0 to accommodate FpML better, and instead recommended a number of potential workarounds. One of these potential workarounds was to implement a set of wrapper elements around FpML to better integrate with WSDL; these wrapper element would provide distinct root elements for each message type.

2.3. AWG Vote

In January 2007, the FpML Architecture Working Group (AWG) voted in favor of the following resolution:

Message Root Elements. It has been proposed that the use of type substitution on the FpML root element be discontinued in favour of element based discrimination. The discriminating element could be positioned as a root or within a revised message structure.

Having separate root elements will:

· Make integration with WSDL easier to accomplish although there may still be issues with type substitution elsewhere (e.g. for block trade identifiers and user extensions).[1]

However:

· It will affect all current implementations of FpML.

· Is no easier to discriminate messages than the existing scheme (e.g. in an XPath expression //FpML/@xsi:type=”SomeMessageType” vs /someMessageType)

2.4. Implementation

After the resolution was passed, several AWG members proposed ways that the resolution could be implemented, but there was no consensus on which was agreed or preferable.

2.5. FpML Change Guidelines

The existing FpML Change Guidelines have the following provisions related to the FpML root element (excepted from section 4 (i) of version 1.0 of the FpML Change Guidelines):

The following types of changes are impermissible:

· Change to the name of the FpML root element.

· Change to the name or existence of the “version” attribute of the FpML root element.

This implies that any change to the FpML root element name version or attribute would require a change to the Change Guidelines by the FpML Standards Committee.

3. Problems and Objectives

This section summarizes issues with the existing FpML root model and proposes objectives for any change in the model.

3.1. Problems with current FpML Root implementation

The main issues with the current FpML root element design include:

· The use of xsi:type to define the FpML content model doesn’t work well with some standards and tools, and is hard for some people to understand.

· The use of a single root element for all FpML messages makes it difficult for a wrapper (such as WSDL) to specifically identify the expected structure and content of an embedded FpML document.

3.2. Objectives of the proposed change

The objectives of the proposed change to the FpML message root are:

· Make FpML usable by more people and tools by eliminating xsi:type in the root element

· Simplify integration of FpML with wrappers such as WSDL by providing a mechanism for the wrapper to specify the desired content model.

· Make FpML as consistent as practical with practices adopted by other standards.

4. Root elements in relevant XML standards

4.1. Introduction

This section surveys practices for root elements in related XML standards, including:

· FIXML

· ISO 20022 XML (UNIFI)

· WSDL 1.0/2.0

· SOAP

· ebXML

At the end, if briefly summarizes observations about how the different standards approach root elements.

4.2. FIXML

FIXML 4.4 documents have a root element named “FIXML”. This element has no attributes other than namespace definitions, schema mappings, and the like, plus some schema-defined fixed version attributes. Inside the FIXML element is an element that corresponds to the message type. It is contained in a substitution group (see below for more details).

Following is an example of a FIX order message:

<FIXML xmlns="http://www.fixprotocol.org/FIXML-4-4"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://www.fixprotocol.org/FIXML-4-4

../../schema/fixml-main-4-4.xsd" v="4.4" r="20030618" s="20040109">

</Order>

</FIXML>

The FIXML root element is defined as follows (starting with the version attributes):

<xs:attributeGroup name="FixmlAttributes">

<xs:attribute name="v" type="xs:string" fixed="4.4"/>

<xs:attribute name="r" type="xs:string" fixed="20030618"/>

<xs:attribute name="s" type="xs:string" fixed="20040109"/>

</xs:attributeGroup>

<xs:element name="FIXML">

<xs:complexType>

<xs:choice>

<xs:element ref="Message"/>

<xs:element name="Batch" type="Batch_t" maxOccurs="unbounded"/>

</xs:choice>

<xs:attributeGroup ref="FixmlAttributes"/>

</xs:complexType>

</xs:element>

In the above, the “Message” element is a reference to an abstract element in a substitution group, similar to the way FpML defines and uses “product” and “underlyingAsset” substitution groups. The “Batch” element is a structure that contains a batch header and 0 or more Message elements.

4.3. ISO 20.022 XML (UNIFI)

The ISO 20022 XML Design Rules (ISO/TS 20022-4, dated 2004-12-15) do not appear to explicitly define the root element name for ISO 20022 XML instance documents. Section 3.3.3.2 describes how the message name in UML is mapped to a XML “root” element. However, all examples and known implementations appear to assume the message documents will have an enclosing document root element called ‘Document’. [Andrew Jacobs: can you identify if/where this practice is explicitly specified?] Each message references its own unique namespace that contains copies of all the types required to define its content (i.e., there are no common schemas used to represent shared types).

Following is an example of FpML contained within SWIFT transport wrapper carrying an ISO 20022 payload (which in turns carries the FpML). The highlighted lines demonstrate the ISO 20022 approach (the others are SWIFT-specific or FpML).

<SwInt:SendRequest xmlns:SwInt="urn:swift:snl:ns.SwInt"

xmlns:SwGbl="urn:swift:snl:ns.SwGbl"

xmlns:Sw="urn:swift:snl:ns.Sw"

xmlns:SwSec="urn:swift:snl:ns.SwSec" >

<SwSec:AuthorisationContext>

<SwSec:UserDN>cn=%4,cn=mnop,o=bankus33,o=swift</SwSec:UserDN>

</SwSec:AuthorisationContext>

<SwInt:Request>

<SwInt:RequestControl>

<SwInt:DeliveryCtrl>

<SwInt:DeliveryMode>SnF</SwInt:DeliveryMode>

<SwInt:NotifQueue>bankus33_notif!p</SwInt:NotifQueue>

<Sw:DeliveryNotif>FALSE</Sw:DeliveryNotif>

</SwInt:DeliveryCtrl>

</SwInt:RequestControl>

<SwInt:RequestHeader>

<SwInt:Requestor>o=bankus33,o=swift</SwInt:Requestor>

<SwInt:Responder>cn=config,o=exchgb2l,o=swift</SwInt:Responder>

<SwInt:Service>swift.fpml.st!p</SwInt:Service>

<SwInt:RequestType>defp.001.001.01</SwInt:RequestType>

<SwInt:RequestRef>CEN/2004/01/05/15-39</SwInt:RequestRef>

</SwInt:RequestHeader>

<SwInt:RequestPayload>

<Ah:AppHdr xmlns:Ah="urn:swift:xsd:$ahV10">

<Ah:MsgRef>CEN/2004/01/05/15-39</Ah:MsgRef>

<Ah:CrDate>2007-12-12T15:38:00Z</Ah:CrDate>

</Ah:AppHdr>

<Doc:Document xmlns:Doc="urn:swift:xsd:defp.001.001.01">

<Doc:CtrctCretd>

</FpML>

</Doc:CtrctCretd>

</Doc:Document>

</SwInt:RequestPayload>

</SwInt:Request>

</SwInt:SendRequest>

4.4. WSDL 1.1

WSDL 1.1 is a standard for defining web services, and as such its structure is similar to, for example, XML Schema. It contains a single “definitions” root element which in turn contains a series of definitions of WSDL constructs such as types, messages, portTypes, bindings, and services.

Following is an abbreviated sample of WSDL, from the WSDL 1.1 specification:

<definitions name="StockQuote"

targetNamespace="http://example.com/stockquote.wsdl"

xmlns:tns="http://example.com/stockquote.wsdl"

xmlns:xsd1="http://example.com/stockquote.xsd"

xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"

xmlns="http://schemas.xmlsoap.org/wsdl/">

<types>

<schema targetNamespace="http://example.com/stockquote.xsd"

xmlns="http://www.w3.org/2000/10/XMLSchema">

</schema>

</types>

</message>

</definitions>

WSDL 1.1 defines messages with reference to elements and/or types, and therefore should be able to reference FpML message types. (The message “type” attribute is not shown here in the example, but is included in the WSDL 1.1 definitions).

4.5. WSDL 2.0

WSDL 2.0, a revised version of WSDL, introduces new structure into the web services definitions, and revises the syntax used.

Following is an extract of the syntax used to represent WSDL 2.0 operations, from the 27 March 2006 WSDL 2.0 Candidate Recommendation:

<input

messageLabel="xs:NCName"?

element="union of xs:QName, xs:token"? >

<documentation />*

[ <feature /> | <property /> ]*

</input

<output

messageLabel="xs:NCName"?

element="union of xs:QName, xs:token"? >

<documentation />*

[ <feature /> | <property /> ]*

</output

</operation>

</interface>

</description>

The important consideration from an FpML perspective is that WSDL 2.0 defines inputs and outputs with reference to element names, and not types. This was the basis of Matthew Rawlings’ comment on WSDL 2.0, discussed in section 2.2. Consequently, for WSDL 2.0 to discriminate between FpML message types it must be able to reference a specific global element for each different FpML message. It is currently not possible to do this directly, as there are no global elements defined for any FpML message.

However, WSDL allows the definition of schema components within the WSDL specification itself (see highlighted section). For example this is the WSDL specification for the HandCoded validation webservice (this uses WSDL 1.1; a subsequent example will short WSDL 2.0 syntax):

<?xml version="1.0" encoding="utf-8" ?>

- wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" xmlns:tns="http://handcoded.com/webservices/FpML/Validation" xmlns:s="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" targetNamespace="http://handcoded.com/webservices/FpML/Validation" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">

- wsdl:types

- s:schema elementFormDefault="qualified" targetNamespace="http://handcoded.com/webservices/FpML/Validation">

- s:element name="Validate">

- s:complexType

- s:sequence

s:element minOccurs="0" maxOccurs="1" name="document" type="s:string" />

</s:sequence

</s:complexType

</s:element

- s:element name="ValidateResponse">

- s:complexType

- s:sequence

s:element minOccurs="0" maxOccurs="1" name="ValidateResult" type="s:string" />

</s:sequence

</s:complexType

</s:element

</s:schema

</wsdl:types

- wsdl:message name="ValidateSoapIn">

wsdl:part name="parameters" element="tns:Validate" />

</wsdl:message

- wsdl:message name="ValidateSoapOut">

wsdl:part name="parameters" element="tns:ValidateResponse" />

</wsdl:message

- wsdl:portType name="FpMLValidationSoap">

- wsdl:operation name="Validate">

wsdl:input message="tns:ValidateSoapIn" />

wsdl:output message="tns:ValidateSoapOut" />

</wsdl:operation

</wsdl:portType

- wsdl:binding name="FpMLValidationSoap" type="tns:FpMLValidationSoap">

soap:binding transport="http://schemas.xmlsoap.org/soap/http" />

- wsdl:operation name="Validate">

soap:operation soapAction="http://handcoded.com/webservices/FpML/Validation/Validate" style="document" />

- wsdl:input

soap:body use="literal" />

</wsdl:input

- wsdl:output

soap:body use="literal" />

</wsdl:output

</wsdl:operation

</wsdl:binding

- wsdl:binding name="FpMLValidationSoap12" type="tns:FpMLValidationSoap">

soap12:binding transport="http://schemas.xmlsoap.org/soap/http" />

- wsdl:operation name="Validate">

soap12:operation soapAction="http://handcoded.com/webservices/FpML/Validation/Validate" style="document" />

- wsdl:input

soap12:body use="literal" />

</wsdl:input

- wsdl:output

soap12:body use="literal" />

</wsdl:output

</wsdl:operation

</wsdl:binding

- wsdl:service name="FpMLValidation">

- wsdl:port name="FpMLValidationSoap" binding="tns:FpMLValidationSoap">

soap:address location="http://www.handcoded.com/FpMLValidation.asmx" />

</wsdl:port

- wsdl:port name="FpMLValidationSoap12" binding="tns:FpMLValidationSoap12">

soap12:address location="http://www.handcoded.com/FpMLValidation.asmx" />

</wsdl:port

</wsdl:service

</wsdl:definitions

It has been asserted that definition of elements in the WSDL specification will not work if they are complex types (e.g. FpML message types) but this restriction does not appear to be in the W3 WSDL specification itself and some examples in the primer seem to indicate that there isn’t a problem.

It is also unclear whether anyone developing webservices with FpML would want to bind directly to FpML types as this would make the interface version specific making updates to new releases more difficult. This is why HandCoded pass FpML as strings in this example so it can validate any FpML version (1.0 thru 4.2).

In WSDL 2.0, local types can also be declared as shown in this example from the WSDL 2.0 primer:

<description

xmlns="http://www.w3.org/2006/01/wsdl"

targetNamespace= "http://greath.example.com/2004/wsdl/resSvc"

xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc"

xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc"

. . . >

...

<types>

<xs:schema

xmlns:xs="http://www.w3.org/2001/XMLSchema"

targetNamespace="http://greath.example.com/2004/schemas/resSvc"

xmlns="http://greath.example.com/2004/schemas/resSvc">

<xs:element name="checkAvailability" type="tCheckAvailability"/>

<xs:complexType name="tCheckAvailability">

<xs:sequence>

<xs:element name="checkInDate" type="xs:date"/>

<xs:element name="checkOutDate" type="xs:date"/>

<xs:element name="roomType" type="xs:string"/>

</xs:sequence>

</xs:complexType>

<xs:element name="checkAvailabilityResponse" type="xs:double"/>

<xs:element name="invalidDataError" type="xs:string"/>

</xs:schema>

</types>

. . .

</description>

Based on the above, it would appear possible to create a set of FpML wrapper elements in WSDL 2.0 and directly reference the corresponding FpML types. However, it would be necessary to create an example and it is not clear exactly how to test a WSDL 2.0 implementation.

4.6. SOAP 1.1

SOAP (originally Simple Object Access Protocol) defines a specification for represent service request. SOAP defines a set of wapper structures that encapsulate an individual request or response. Specifically, SOAP defines an Envelope (root element) that contains a Header and a Body, as follows (in a simplified form):

<soap:Envelope>

<soap:Header>

</soap:Header>

<soap:Body>

</soap:Body>

</soap:Envelope>

In effect, SOAP defines a standard root element and header structure to assist recipients to process the requests. SOAP can be used to wrap FpML messages or requests by including the FpML as part of the SOAP Body.

4.7. ebXML

ebXML is defined by extending SOAP with attachments, by adding extensions to the SOAP Header and Body. For this reason, the ebXML standard can be treated similarly to SOAP for our purposes.

4.8. Summary of standard survey

· All of the standards identified above use a single, standard element name as their entry point. In some of the cases (e.g. FIXML, FpML) this element name is based on the standard’s name; in most cases (especially the more horizontally-oriented standards) this element name is generic (e.g., “Document”, “definition”, “envelope”, etc.)

· Only FpML makes use of xsi:type for defining document/message structure.

· Other methods used for defining document/message structure include substitution group (FIXML), distinct namespaces and schemas (ISO 20022), and single standard structure with optional elements (WSDL 1 and 2, SOAP).

· There is some lack of clarity about what exactly will work with WSDL 2.0 and how to test this, as we have not identified implementations of WSDL 2.0 at this time.

5. Implementation Options

5.1. Introduction

This section proposes several options for implementing the AWG vote of January 2007 on eliminating the use of xsi:type in the FpML root element.

It documents assumptions about the options to be examined, then proposes three specific implementations:

· New wrapper elements around the FpML element

· Replace xsi:type (type substitution) with a substitution group of message elements under the FpML root element

· Eliminate the FpML root element and replace with separate root elements for each message.

· Leave FpML as it is in version 4.x