Rich Newman

December 29, 2007

Introduction to using Financial Products Markup Language (FpML) with Microsoft .NET Tools (Part 1)

Introduction

This short series of articles will attempt to show how Microsoft’s standard .NET tools (Visual Studio and xsd.exe) can be used to investigate and use Financial products Markup Language (FpML).

This first article gives an overview of how we can use Visual Studio to examine the FpML XSDs, and use it to validate the XML examples that are provided in the FpML download.

Part 2 of the series will examine how the FpML XSDs fit together for basic trade types.

These articles assume you understand the basics of XML Schema Definition language. If you don’t there are a number of good tutorials available on the internet. For example there’s quite a good one at http://www.w3.org/TR/xmlschema-0/. These articles will reference the tutorial for the less obvious XSD structures.

FpML

Financial products Markup Language is intended as an industry-standard method of representing financial products using XML. Details can be found at www.fpml.org.

The XML representations of financial products are defined using XML Schema Definition (XSD). These can be downloaded from the site.

FpML is Complex

The FpML XSDs are intended to define XML for a very wide range of financial products. They are also intended to be easily extensible for any new products. To achieve this products are built up from small building blocks into a complex structure. This means the XML is very hierarchical (it has many layers of tags).

An alternative approach would be to represent financial products in as flat a structure as possible. By ‘flat’ we mean a simple series of name-value pairs (with associated types for the values), and no hierarchy. Even quite complex derivatives products can be represented by a flat schema (obviously such things as basket products are an exception to this). A flat structure is easier to understand, and can be easier to handle in code. It also leads to less verbose XML, and hence smaller message sizes.

However, this is not the approach FpML takes for good reasons: whilst it’s easier to deal with a flat structure, it’s hard to extend as you cannot easily re-use blocks of tags in a new structure.

As well as defining formats for a wide range of trade types, the FpML XSDs define message formats for standard trade events (e.g. confirmations, credit event notifications). They also define standard enumerations for such things as day count conventions.

As a result all this FpML is inevitably complex and difficult to understand. Furthermore there’s little free documentation available.

Visual Studio Support for XSDs

Visual Studio (combined with C#) has good support for XML and XSD. As you may know, we can load XSDs into it and it will automatically check that they are internally consistent. We can then load XML into it and validate that XML against the XSDs on the fly at design-time.

As we shall show the .NET languages also have support for validating XML using XSDs at run-time.

In addition there is an ‘XML Schema Definition Tool’ called xsd.exe that ships with Visual Studio. We can use this to automatically generate classes in a .NET language of our choice based on the XSDs. We can then load the XML data into those classes (at run-time obviously). If we don’t like the classes it’s very easy to manually tweak them to do what we want. In fact, as we shall see, xsd.exe is far from perfect and we may well need to tweak the classes to get them to work properly.

We can even usually use xsd.exe to generate DataSets from the XSDs and populate those from the XML. Of course, DataSets give us some disadvantages (e.g. speed) over plain old classes, but they allow us to track changes, and easily bind our data into grids for display and editing.

This series of articles will take us through all of the scenarios outlined above. However, as we shall see, the complexity of the FpML schemas (and some Microsoft bugs) can make handling FpML in Visual Studio challenging.

Initially we will work with Visual Studio 2005 (and .NET 2.0). Later on we’ll have a look at changes in Visual Studio 2008.

Getting Started with FpML and Visual Studio

The first thing to do if you want to learn about FpML is to download the schemas. This can be done from www.fpml.org, although you will need to register with the site. For this article I have used the FpML 4.2 Recommendation in Zip format, which you can download via the ‘Specifications’ tab.

Once you have downloaded and extracted this, create a console application project in Visual Studio. Add ALL of the XSDs found in the xml folder from your download to this project (using the Project/Add Existing Item… menu).

XSD

We are going to start with interest rate swaps. The details of these are defined in file fpml-ird-4-2.xsd. Right-click this file in Solution Explorer and select View Code. DON’T just ‘Open’ it as the default is to open with a DataSet Editor, which gives a graphical view. Note that you can change the default if you right-click/Open With. If you select the XML Editor as the default you will get the code view when you double-click in future.

You should now have the raw XSD in the document window. It’s a bit daunting, so right-click in the document window, and select Outlining/Toggle All Outlining. This collapses the XSD entirely. If you now expand it once (by clicking the ‘+’ sign) you will see that the XSD includes some other schemas, then defines some complex types, then some elements and some groups. One of the elements is called ‘swap’, which is encouraging. This is of type ‘Swap’ which we can see defined as a complex type. However it’s not clear how we get from this to XML for an interest rate swap.

Note here that Visual Studio validated the schema when you displayed it. You can see this if you deliberately break the schema. Try changing the type of the swap element mentioned above to ‘notSwap’. If you now look at the Warnings in the Error List (menu View/Error List) you’ll see Visual Studio is telling you that ‘Type ‘http://www.fpml.org/2005/FpML-4-2:notSwap’ is not declared.’ It’s also telling you the line number and the file, and you can as usual double-click the error to go to it.

notswap.jpg

Note also that Visual Studio only validates the schema when the schema file is open in the document window (try saving it and closing it with the error still in there: the warning disappears). Visual Studio will quite happily validate all of the FpML XSDs if you open them individually however.

XML

Now we will add an XML file representing an interest rate swap to our project, and get the XSDs to validate it. Our original download contains XML examples in the subfolders of the xml folder referred to above. In particular, there is a folder called interest-rate-derivatives that contains a file called ird_ex01_vanilla_swap.xml. This XML file references the XSD files we have already examined using the schemaLocation attribute. However the schemaLocation attribute says that the schemas are in a folder at a level above the XML file.

So create a folder in your solution (right-click the solution in Solution Explorer and select Add…/New Folder). Then right-click the folder, choose Add/Existing Item…, and add the ird_ex01_vanilla_swap.xml file into this folder.

Now if you open the file in Visual Studio it should validate correctly straight away: there should be no errors or warnings in the Error List. Again you can see this is working if you manually edit the XML: try changing the partyReference element near the top to ‘notpartyReference’. You will get a warning the notpartyReference is an invalid child element and ‘partyReference’ is expected.

notpartyreference.jpg

Visual Studio and XML: Navigation and Outlining

We have already seen that we can use Visual Studio’s outlining (collapsible regions) in the usual way with XSD files, and the same is true of XML files.

We can also use Visual Studio’s standard ‘Go To Definition’ functionality with both XSD and XML files. Put your cursor inside partyReference in the XML and hit F12 (or right-click, Go To Definition). Visual Studio will show the place in the XSD where partyReference is defined (which is inside file fpml-doc-4-2.xsd).

This shows that partyReference is an element in complex type TradeIdentifier. It is itself of type ‘PartyReference’. If you right-click ‘PartyReference’ and Go To Definition in the same way you can navigate within the XSD: you can see that PartyReference is an extension of base type ‘Reference’, and if you go to the definition of that you can see that it is an abstract complex type with one attribute called ‘href’ of type IDREF.

You can then navigate back through the items you’ve visited as usual in Visual Studio using the Navigate Backward toolbar button, or hitting Control + – (minus key).

It’s worth noting that the normal toolbar Comment/Uncomment buttons work fine with XML and XSD, including commenting sensibly across several lines: you don’t have to type ‘<!–‘ and ‘–>’. Also there’s good intellisense support if you are entering XML or XSD code, including code snippets on the context menu.

Finally if you load all of your XSDs into a project as described above you can (obviously) use Visual Studio’s normal Find in Files functionality (Ctrl-Shift-F) to locate items anywhere in the XSDs.

Validation in Code

We have seen how we can use Visual Studio to validate that a schema is correctly formed, and to validate an XML instance document against a schema. We can also do this validation in C# code.

Validation of a Schema in Code

To validate a schema we can load it into an XmlSchemaSet and compile it as below. Put this code in the Main method of the C# console application created above to see this working:

            XmlSchemaSet xmlSchemaSet = new XmlSchemaSet();
            xmlSchemaSet.Add("http://www.fpml.org/2005/FpML-4-2", @"..\..\fpml-main-4-2.xsd");
            xmlSchemaSet.Compile();

If the schemas are not properly formed you will get an error when you attempt to compile them.

Validation of XML Against a Schema in Code

To validate an XML instance document against the schema we use an XmlReader in association with a ValidationEventHandler as below. The code below goes in Main:

            XmlReaderSettings xmlReaderSettings = new XmlReaderSettings();
            xmlReaderSettings.Schemas.Add(xmlSchemaSet);
            xmlReaderSettings.ValidationType = ValidationType.Schema;
            xmlReaderSettings.ValidationEventHandler += new ValidationEventHandler(xmlReaderSettings_ValidationEventHandler);
 
            XmlReader xmlReader = XmlReader.Create(@"..\..\XML\ird_ex01_vanilla_swap.xml", xmlReaderSettings);
            while (xmlReader.Read()) { };
 
            Console.WriteLine("Validation complete");
 
            Console.ReadLine();

Additionally we need a ValidationEventHandler method: this will be called if there are any errors:

        static void xmlReaderSettings_ValidationEventHandler(object sender, ValidationEventArgs e)
        {
            if (e.Severity == XmlSeverityType.Warning)
            {
                Console.Write("WARNING: ");
                Console.WriteLine(e.Message);
            }
            else if (e.Severity == XmlSeverityType.Error)
            {
                Console.Write("ERROR: ");
                Console.WriteLine(e.Message);
            }
        }

The code for this example is available. To test these try deliberately breaking both the schemas and the XML and ensure you get appropriate error messages. Note that this code is based on Microsoft’s own help examples at http://msdn2.microsoft.com/en-us/library/3740e0b5(VS.80).aspx.

Note on Visual Studio 2008

The above discussion used Visual Studio 2005. Visual Studio 2008 behaves in the same way except:

  1. Visual Studio 2008 defaults to the XML Editor as the editor for XSD files, which is more sensible than the default DataSet Editor in Visual Studio 2005.
  2. Visual Studio 2008 automatically references xmlsig.xsd in Microsoft’s own schemas folder (normally c:\Program Files\Microsoft Visual Studio 9.0\xml\Schemas). xmlsig.xsd is the standard XML Signature namespace. However, the FpML files are referencing their own version of this schema, which is called xmldsig-core-schema.xsd. As a result if you open fpml-main-4-2.xsd in the designer, for instance, you get warnings about types in this schema being defined twice.To fix this bring up the Properties window for the fpml-main-4-2.xsd file, and click in the Schemas property. Click the button that appears. The screen that comes up lets you select the schemas that are automatically used for the file. Find xmlsig.xsd and in the ‘Use’ column set it to ‘Do not use this schema’ (which gives it a red cross as below). This will get rid of the warnings.

dontuseschema.jpg

Conclusion

This article has looked at some of Visual Studio’s functionality for handling XSDs and the associated FpML. Part 2 of this series will examine how the FpML fits together for a basic trade XML document.

Licensing of FpML Specifications

The FpML Specifications of this document are subject to the FpML Public License (the “License”); you may not use the FpML Specifications except in compliance with the License. You may obtain a copy of the License at http://www.FpML.org.
The FpML Specifications distributed under the License are distributed on an “AS IS” basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License.
The Licensor of the FpML Specifications is the International Swaps and Derivatives Association, Inc. All Rights Reserved.

http://www.fpml.org/documents/license.html

About these ads

4 Comments »

  1. i am getting security exception with your C# validation project

    xmlSchemaSet.Add(“http://www.fpml.org/2005/FpML-4-2″, @”..\..\fpml-main-4-2.xsd”);

    Request for the permission of type ‘System.Security.Permissions.FileIOPermission, mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089′ failed.

    Comment by Stanislav — February 5, 2008 @ 6:58 pm

  2. Stanislav

    Have you saved the code to your local drive (C:)? By default .Net will not run code on remote network shares, and will give this error.

    Rich

    Comment by richnewman — February 21, 2008 @ 1:13 pm

  3. Hi,

    Very nice article. Thanks.
    I have a question:
    Do you have an easy solution for showing various pieces of an FpML document in Excel?
    I tried mapping FpML documents to DataSet, but I get DuplicateNameException.

    Comment by Daniel — March 20, 2008 @ 8:43 pm

  4. i tried a slightly different approach …

    http://hosca.com/blog/post/2008/12/26/Generating-C-classes-from-FpML-Schema.aspx

    Comment by Erhan Hosca — December 29, 2008 @ 6:07 pm


RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

The Shocking Blue Green Theme. Create a free website or blog at WordPress.com.

Follow

Get every new post delivered to your Inbox.

Join 81 other followers

%d bloggers like this: