Copyright (C) 2003. All rights reserved.
Financial Products Markup Language is subject to the FpML public license
A copy of this license is available at http://www.fpml.org/documents/license
The FpML Architecture Version 2.0 Working Draft defines that standards and principles on which the FpML grammatical definitions are based.
The FpML 2.0 Architecture builds upon the earlier FpML 1.0 Architecture specification and the conventions of FpML 1.02b before that. The refinement of the FpML architecture is an evolutionary process bought about by changes in the XML technology upon which it is based and the requirements of the standard as its scope expands.
This section highlights the most significant changes that have been made to the architecture standards since the last release.
Up until FpML 3.0 intra-document links between elements were made using ID attributes to label elements that could be referenced and CDATA attributes using XLink syntax to record the actual references.
At the time it was our belief that support for XLink would be included in future XML parsing technology to allow such references to be automatically validated. Support for XLink has not developed as we expected and its use is now primarily constrained to 'hyper-linking' collections of arbitrary documents. As a result in FpML 3.0 and its successors intra-document references have been redefined as IDREF attributes.
This change creates an incompatibility between pre-3.0 documents and the later standards. In XLink syntax a reference to an ID attribute is represented as string starting with a hash/pound character ('#') followed by the name of the target identifier. The hash/pound character is not allowed in an IDREF value and must not be present in documents based on FpML 3.0 or later.
When converting documents from pre-3.0 to later the character may simply be removed. For example the equivalent of the pre-3.0 XLink reference '#ISDA' is just 'ISDA'.
This simple change means that the XML parser can now check that very reference is satisfied by some element within the document. It should be noted however that using IDs and IDREFs alone the parser can not check that references are resolved to the correct type of target element (e.g. an IDREF that is supposed to reference a party could in fact match an ID on a non party element).
This specification contains guidelines on the use of schema key and keyref definitions that can provide this extra integrity.
From FpML 4.0 the normative implementation of the FpML grammar will be represented as a set of XML schemas. The XML schema standards contains a far richer set of features that will assist in the development of large and complex grammars such as FpML.
The use of namespaces is inherent in XML schema based grammars since every document must reference at least one to access the definitions for XML schema itself. This means that the architecture specification must be updated with respect to namespaces as the 1.0 version had disallowed their use due to inconsistent implementation in DTD based parsers.
There are no plans to formally maintain a DTD version of the FpML 4.0 and subsequent grammars.
Element definitions in DTD based grammars are inherently global, that is within a given namespace each element name may be declared only once and all uses of it will imply the same content model. The non-normative translation to XML schema provided with FpML 3.0 mirrored this feature of DTDs by declaring all elements as global within the schema.
The experience of adding more product and message types in FpML 4.0 has lead us to believe that it is important to be able to reuse an element name, adjusting its definition and content to suit its new context. Accordingly in FpML 4.0 where possible element definitions have been made local to a containing complex type.
This change means that the only cases where an element may declared globally with in the FpML schema are:
The root element for FpML itself (e.g. <FpML>).
An element which participates in a substitution group (e.g. <product>, <swap>)
Although the concept of enumerated values existed in DTDs it only applied to values held in attributes. XML schema widens the support for enumerations to cover values held in elements.
A large number of the schemes defined for FpML 1.0, 2.0, and 3.0 were good candidates for replacement with enumeration and with effect from FpML 4.0 they will be modelled as such within the schema. Additional guidelines have been added to the architecture specification on the definition of enumeration values.
XML Schema allows for the embedding of (multi-lingual) annotations against every schema component definition. This feature is used extensively in FpML 4.0 to allow the reference documentation to be directly generated from the schema itself.
Embedding the documentation in this manner enlarges the size of the schema but only seems to have a marginal affect on parsing performance. However some FpML schema users may wish to remove it from the schema if it proves to be a problem in time critical processing tasks.
Another significant extension to FpML in version 4.0 is the inclusion of a framework for messaging. To date FpML has concentrated on creating post trade product definitions. The messaging framework allows FpML to extend into defining both 'Business to Business' (B2B) and 'Application to Application' (A2A) business processes modelled as a sequence of exchanged message types.
To support this new content the message model makes use of XML schema features such as type substitution, restriction and local content. It has also driven other changes, such as the removal of scheme defaults, that make processing and responding to messages easier.
The migration to schema and messaging has provided an opportunity to revisit the issue of how 'code' values should be referenced from within documents.
In the FpML 1.0 specification all such values are referenced through the scheme mechanism where each code value has an associated URI specification to determine its context. This allows the same code to appear in more than one coding scheme and maintain the correct interpretation where ever it is used. To help reduce document size a defaulting convention was established for scheme URIs using attributes on the root <FpML> element.
With effect from FpML 4.0 a new convention will be adopted which allows greater use of schema based validation for some types of scheme. The changes can be summarized as follows:
All the scheme default attributes have been removed from the root <FpML> element.
Simple schemes consisting of a small fixed set of values (e.g. days of the week, date roll conventions, etc.) have been replaced by enumerations defined within the FpML schema. Enumerations are defined using schema simple types to allow reuse of a common definition by several elements.
For elements referencing FpML (or other standards body) defined code values the scheme reference attribute remains optional but has been given a default value which is standard URI for that scheme defined for a particular FpML version.
For elements referencing institution specific codes (e.g. trade and message identifiers, etc.) the scheme reference attribute has been made required.
The adoption of these changes means:
It is no longer necessary to change the <FpML> element every time a new scheme is added to the schema.
Documents cannot contain references to schemes which are unnecessary to their purpose.
The interpretation of code values in a section of XML is unchanged if it is copied into a new document, for example during message processing.
Throughout the development of FpML the Architecture Working Group has looked to other forums and standards groups for guidance and advice on the best way to use XML schema. The results of searches for information on best practice have largely been disappointing.
Much of the information on 'Best Practice' publicly available on Internet does not apply to the finance domain. Many of the available documents are based on draft releases of the specification rather than the final recommendation. Often the position argued is based on the assumption that the data represents the persistent state of some object oriented data structures (rather than a model of present day information sources with all its irregularities), or is based on a poor understanding of schema and the interplay between its features.
The schema standard itself is a compromise between two schools of thought, namely Object Oriented Design and Information Modelling. It frequently offers more than one solution to a design problem, each with its own set of trade offs for re-use and extensibility. As a consequence we have concentrated on determining how best to use the features of XML schema to model financial information for FpML, rather the best approach for all problems.
Readers wishing to research into best practice for themselves might like to start with the following links:
Following the publication of this document the AWG will continue its investigations into determining the best way to represent the FpML grammar and manage the complexity created by its expansion into new product areas and business processes as well as the more practical issues such as offering guidance on implementation.
To simplify to move to XML schema and minimise the impact on existing FpML documents the current grammar is represented as definitions in a single namespace. As the size of the schema grows this approach is likely to become unmanageable. In particular:
Most documents use only a fraction of the total number of definitions in the schema. Breaking up the schema into a set of small components, would minimise the amount of schema required for each document.
The change to local element definition allows element names to be reused unambiguously. A change to multiple namespaces would allow complex type names to be reused as well (e.g. allowing common terms such as price and rate to be defined to suit individual products).
A more modular schema would allow extensions to be added (e.g. new products or business processes) with little or no modification of existing components.
The AWG needs to examine further the implications of such a change in detail, such as the effect on document size (from extra prefixes) and common processing tools (e.g. XSLT). In addition the impact of multiple namespaces on the versioning mechanism needs to be assessed.
The AWG considers validation to be a multi-stage problem, as illustrated by the following list.
Syntax
Checking that a document conforms to the syntax imposed by a grammar is the most basic form of validation possible. The content rules and data type definitions within the FpML schema allow the XML parser to check a document's syntax during processing.
Referential Integrity
To avoid duplication of data in a document the FpML grammar allows definitions made in one section of a document to be referenced elsewhere. The underlying mechanism for this reference does not check that referenced information is of an appropriate type however it can be enhanced with additional XML schema definitions to allow validation during parsing.
Semantic
Ensures that the 'business object' components of the document contain values that are consistent with each other and that the correct structural choices have been made to define the object.
Procedural
Ensures that information contained within a document is pertinent to the business process to which being applied and that the order in which the document is processed relative to other documents describing operations on the same 'business object'.
Institutional
Each user of FpML is at liberty to place additional constraints on the FpML documents that they consider valid. Such constraints might be applied to any facet of an FpML document (e.g. a message type, a party, product definition) and will vary from firm to firm. The implementation of such additional rules might exist in hardwired program code or as a set of interpreted rules (e.g. Schematron, XLinkIt, etc.) and is outside the scope of FpML.
The AWG believes that the simpler validation stages should be implemented in a standard manner to guarantee consistent processing by FpML processors. To this end it is investigating the use of integrity features within the XML schema language. Higher level validation requires more sophisticated processing that can currently be provided by XML schema and is currently being researched by the Validation working group.
This section defines the FpML style for structuring XML schema. It defines the rules as they apply to the various components of an XML schema and shows how the basic elements of object oriented design would be mapped to XML types and elements.
The rules in this section have been based on the following XML schema recommendations:
XML Schema Part 1: Structures
XML Schema Part 2: Data Types
Additional information on XML schema and its usage can be found in this associated document:
XML Schema Part 0: Primer
FpML uses a subset of the built-in data types as defined in the "XML Schema Part 2: Data Types" recommendation 2 May 2001 to define the type associated with simple scalar business data values (e.g. amounts, dates, names, etc.). The full set of built-in types available to an XML schema designer is defined in the following section of the standard.
If required, the size and other properties of these data types may be specified using the facets for them as described in the recommendation above. Examples are:
http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/#rf-length
http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/#dt-totalDigits
http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/#rf-fractionDigits
FpML uses two naming conventions throughout its definitions (sometimes with an additional suffix). In this document these conventions are referred to as 'lowerCamelCase' and 'UpperCamelCase'.
An identifier conforming to lowerCamelCase convention MUST have:
First word or acronym in lower case.
All following words or acronyms with upper case first letter.
All other characters are lower case.
Numbers may appear between words or acronyms or at the end of the name. No other non-alphabetic characters may appear. For example:
href
tradeId
currencyScheme
currency1SideRate
fxAmericanTrigger
An identifier conforming to the UpperCamelCase convention MUST have:
All words or acronyms with upper case first letter.
All other characters are lower case, including the remaining characters or acronyms.
Numbers may appear between words or acronyms or at the end of the name. No other non-alphabetic characters may appear. For example:
Interval
AmountSchedule
FxSpotRateSource
DateRelativeTo
The FpML 4.0 grammar contains a few identifiers that do not confirm architecture specification naming conventions. Many of these identifiers existed within previous release of the grammar and changing them may affect operational systems or their ability to reprocess already archived documents.
This issue of when and how to bring these names into line with the conventions is being discussed by the FpML coordination committee. When corrections to identifier names take place they will be documented as part of the release documentation.
This section defines the design rules that FpML imposes of each feature of the XML schema language to ensure consistency of usage during the modelling process.
All FpML defining schema MUST specify the qualification of their schema components such that:
All FpML defined elements and types MUST be qualified with an appropriate namespace declaration.
All FpML defined attributes MUST be unqualified.
The simplest way to achieve this is to set the qualification defaults on the schema root element as follows:
<xsd:schema xmlns:xsd = "http://www.w3.org/2001/XMLSchema" elementFormDefault = "qualified" attributeFormDefault = "unqualified"> ... </xsd:schema>
FpML allows the use of attributes but restricts their usage to 'meta-data' such as the FpML version number, IDREF based intra-document links and URI definitions for externally referenced items.
No business (e.g. transaction, party or product, etc.) data is allowed to reside within an attribute. FpML favours the use of elements for such information because of their more powerful grammatical and modelling construction capabilities at the cost of larger document sizes.
When an attribute is defined within FpML its name MUST follow the convention of lowerCamelCase:
Attributes SHOULD be associated with either a XML schema built-in type or and FpML defined simple type to allow the parser to validate document instances.
FpML designers SHOULD avoid declaring attributes with global scope, instead they should be locally define within a containing element, type or attribute group.
Attributes groups MAY be used in FpML schemas to create a reusable set of attribute definitions and ensure consistency across a number of element or type definitions.
The name of an attribute group will never appear in an instance document, so its naming is not critical. However for consistency the AWG recommends that it use UpperCamelCase convention with the suffix '.atts' added. For example:
<xsd:attributeGroup name = "StandardAttributes.atts">
<xsd:attribute name = "version" use = "required">
<xsd:simpleType>
<xsd:list>
<xsd:simpleType>
<xsd:restriction base = "xsd:normalizedString">
<xsd:enumeration value = "4-0"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:list>
</xsd:simpleType>
</xsd:attribute>
</xsd:attributeGroup>
Elements define the vocabulary of tag names that can be used in an instance document to markup information. The XML schema language provides several ways in which elements may be used on their own or in conjunction with types to define a complex grammar.
The preferred style for FpML XML schema can be summarized as follows:
All elements other than the document root element (<FpML>) MUST follow the lowerCamelCase naming convention as described for attributes.
All elements MUST be associated with a globally defined type which defines their content (either a single value or a set of structured values).
All elements other than the document root element (<FpML>) and those which are used to create substitution groups MUST be defined locally within a containing complex type or model group.
An FpML schema MAY use substitution groups to create points of extension. In order for substitution to be possible the following standard schema conditions must apply:
The element to be substituted MUST be globally defined.
Substituting elements MUST be globally defined.
Substituting elements MUST be type compatible with the substituted element.
Currently FpML imposes the following extra condition:
The substituted element MUST be abstract to prevent its use in documents.
This final restriction may be removed in future FpML releases to allow type substitution to be used in preference to substitution groups. This change will allow greater use of XML Schema integrity features (e.g. keys and keyrefs) when used inconjunction with user extensions.
<product xsi:type="Swap"> ... Swap content model here </product>
An instance document MAY choose to override the type of an element to substitute it with content defined by another compatible type (i.e. one defined by inheritance). Examples of this can be found in the messaging framework which uses type substitution on the <FpML> element to set the content model for the entire message.
The AWG believes that in most circumstances type substitution is a better approach than substitution groups and where possible should be used in preference (see the later section on extending FpML for examples).
Model groups allow the definition of a grammar fragment consisting of elements and their associated cardinalities. These grammar fragments may be referenced within other element and/or complex type definitions.
Like attribute groups, the name of an model group will never appear in an instance document, so its naming too is not critical. However for consistency the AWG recommends that it use UpperCamelCase convention with the suffix '.model' added. For example the following code defines a small model group consisting of two elements, <a> and <b>.
<xsd:group name = "Common.model">
<xsd:sequence>
<xsd:element name = "a" type = "xsd:integer"/>
<xsd:element name = "b" type = "xsd:decimal"/>
</xsd:sequence>
</xsd:group>
This model group can then be referenced from within the content model of another element or complex type as in the following example.
<xsd:complexType name = "TypeA">
<xsd:sequence>
<xsd:group ref = "Common.model"/>
</xsd:sequence>
</xsd:complexType>
The content defined by such model groups can be combined with other model group references, global element references and/or local element definitions to create more complicated definitions such as the following example.
<xsd:complexType name = "TypeB">
<xsd:sequence>
<xsd:group ref = "Common.model"/>
<xsd:element name = "c" type = "xsd:string"/>
</xsd:sequence>
</xsd:complexType>
Using model groups in this manner with complex types creates structures that are similar to those generated by 'inheritance by extension' (described later), however the resulting types are not formally related and cannot be used in a type substitution (i.e. given the types in the example TypeB cannot substitute TypeA).
FpML allows the definition of simple types, especially where such definitions can be used to provide additional validation of scalar values. When a simple type is defined it MUST have an UpperCamelCase name.
Simple types may be defined as a restriction of an existing simple types (by means of a regular expression) or as a list of values. It should be noted that values accepted by the new type must also be accepted by all the parent types (e.g. it is not possible to remove the seconds component from a time, but you can ensure that it is always zero).
Complex types account for almost all of FpML's XML schema definitions. They are subject to the following conditions:
Complex types MUST be named according to the UpperCamelCase conventions.
A complex type MAY define a content model based on locally defined elements, globally define elements (for substitution groups) or through references to model groups.
A complex type MAY define attributes or reference an attribute group.
FpML allows complex types to be marked as abstract if they provide definition of features common to a number of over complex types that are derived by extension.
The use of inheritance by restriction is allowed between complex types as a way of limiting the content model of an existing type.
XML schema allows the content model for a complex type to be defined in a number of ways. This section describes the prefer options within an FpML schema.
The most common way to specify the structure of some information is as a sequence of elements, each with a given cardinality (e.g. zero, one, unbounded or a specific number). To be valid an instance document must match the order of the elements as defined in the content model (allowing for cardinality).
Sequential defined content MAY contain choice groups whether alternative element orders are possible.
Choice groups define a series of alternative element sequences that may appear with the content.
Care must be taken when defining choice groups to ensure that the grammar remains 'deterministic' (i.e. given a set of alternative rules the parser must be able to select the correct grammatical rule to apply based on the current token and those it has seen previously). For example consider the grammar for a type consisting of two elements, <a> and <b>, which may appear individually or together.
The most obvious grammar is one that simply lists the three possible outcomes that are allowed (e.g. <a>, <b>, and <a><b>) as shown in this diagram.
This grammar is non-deterministic because the two of the rules start with the same element pattern (e.g. <a>) and the parser could select the wrong one. The correct way to express this simple choice is to combine the <a> and <a><b> options into a single rule in which element <b> is optional. Each of the choices now starts with a different element making the correct rule obvious to the parser.
XML schema provides a facility for defining a content model in which the contained elements may appear in any order within the instance document. This style of definition is not relevant to FpML documents and SHOULD NOT be used in FpML define XML schemata.
Designers of FpML XML schemata SHOULD embed documentation within their schema components to enable the production of documentation automatically from the schema source. XML schema allows multiple annotations for each component differentiated by the 'xml:lang' attribute and designers may provide multi-lingual text.
<xsd:element name="valuationTime" type="BusinessCenterTime">
<xsd:annotation>
<xsd:documentation
xml:lang="de">Genaue Tageszeit, zu der die Bewertungsstelle den Basiswert bewertet.
</xsd:documentation>
<xsd:documentation
xml:lang="en">The specific time of day at which the calculation agent values the underlying.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
The FpML organisation WILL maintain a fully annotated XML schema, at each release, as its normative definition of the FpML grammar. The FpML organisation MAY in addition publish non-annotated normative copies of the schema for time critical processing applications (to eliminate the risk that users may inadvertently change the schema whilst removing the annotation themselves).
Broadly speaking, FpML has always used an object-oriented approach for data modelling, however the resulting model has always been expressed directly in XML. Originally its designers used object oriented techniques to design and mapped the result structures into the with the resulting model as either an XML schema or DTD (for releases up to FpML 3.0).
In object-oriented design, a class defines a common set of data attributes and functionality that will be present in any instance of the type. Because XML is not procedural, only the data members of a class are mapped to XML types and elements.
For example, the FpML type used to represent monetary amounts could be represented (using UML) as class with the following structure.
The simplest mapping for such types into XML schema structures is through the use of 'complex types'. Such definitions allow a rich content model to be associated with the class and also the construction of further types through the use of inheritance. Both features are described later. The corresponding XML schema definition for this simple class is shown below.
<xsd:complexType name = "Money">
<xsd:sequence>
<xsd:element name = "currency" type = "xsd:token"/>
<xsd:element name = "amount" type = "xsd:decimal"/>
</xsd:sequence>
</xsd:complexType>
XML schema supports the embedding of textual annotation within schema definitions to describe the role of each definition. This feature should be used to document each of the types and its constituent members, although for brevity such annotations have been omitted from this document.
Frequently the members that comprise a class are related in someway. Often the presence of one may imply the presence or absence of one or more other members. Such relationships can be captured in the XML schema group the use of choice groups.
The existence of a overly complex content model may suggest that a class is poorly designed and would be better factored into either a number of alternative sub-types or should be constructed through aggregation. Sometimes the design may be completely justified as is.
The AWG suggests that designers who find themselves with such models examine the possibility of using inheritance and/or aggregation to see if it would yield a better model. Complex content should only be used if the alternatives are unacceptable.
Inheritance allows for the construction of new types from existing ones. XML schema supports two styles of inheritance, by extension and by restriction, of which the former is the more familiar to object oriented designers and programmers.
XML Schema supports a single inheritance pattern between complex types by extension. Usually the base type represents a 'generalized' structure that becomes more 'specialized' in the derived type. For example in a simple type hierarchy for graphics a base Shape type might hold the location of a shape on the drawing surface (e.g. the top left corner) whilst derived types provide the information required to draw specific types of shape (e.g. side length of a square, radius of a circle, etc.).
Under this style of inheritance the content model inherited from the base type by the new derived type cannot be modified. Any data member defined in a base types will be present in all the derived types with the same cardinality (e.g. optional, one, multiple, etc.).
Inheritance by restriction is an alternative way of defining a specialization where instead of adding additional information during the derivation we take it away. The base type in a restriction represents the most general form of a type, its content typically being the superset of all the data present in all of its derived types. Each sub-type selects a sub-set of the available data members and may select a cardinality for the member which is within the bounds of the original definition (e.g. a non-repeating optional element may be omitted in the derive type but cannot be made repeating).
Inheritance by restriction is useful where each of the sub-type appears to be a variation sharing many similar properties to its siblings.
Where as inheritance by extension has a simple and direct mapping into object orient programming class structures that allow many usage errors to be detected during compilation. If restriction is present then many of checks must be performed at runtime as instances are accessed.
An abstract type is a type that may not be instantiated within a document. Such types are frequently used to represent the properties common to a number of related sub-types, such as financial products.
Abstract types often indicate points in the grammar where users may wish to create their own extensions.
There are two basic approaches for the handling of arrays or sequences of repeating data in XML, namely:
Simply repeat the required element as many times as necessary between its sibling element. This creates the simplest XML definitions and documents. For example:
<fullName> <firstName>Liam</firstName> <initial>A</initial> <initial>C</initial> <familyName>Jacobs</familyName> </fullName>
Define a container to hold the repeating element and use the container in the parent element. This assists in programming message construction and parsing.
<fullName>
<firstName>Liam</firstName>
<initials>
<initial>A</initial>
<initial>C</initial>
<initials>
<familyName>Jacobs</familyName>
</fullName>
Unfortunately most XML book authors use both styles inconsistently in their texts and hence are unreliable references of what constitutes good XML style so the FpML 1.0 Architecture specification choose the simpler representation as the standard for FpML documents. Hence the mapping that would be applied in the case of the following model is simply a repetition of the element <detail> inside the containing <master> between any sibling elements
It has been noted that some other standards have chosen to go with the container approach, however in most cases the container not only provides grouping but also carries additional attributes or elements describing some property of the collection as a whole (e.g. in FixML an OrderList has a ListNoOrders attribute, etc.). If such information where required for a container in FpML then it would be represented as follows, although to date no FpML working group has found the need to do this.
Such a model would result in documents with the following content:
<master>
...
<details>
<count>2</count>
<detail>...</detail>
<detail>...</detail>
</details>
</master>
An association represents a relationship between two independent objects. The relationship normally has a 'role' that represents the purpose to which the associate object is put.
One type may have many associations to same target type provided that the purpose of each association can be determined. A simple way to do this is to use the associations 'role' name to name the element use to record it in an XML document.
Like association, aggregation is a relationship between two objects. However, unlike association, the aggregated object does not have an independent existence.
Aggregation of sub-types is a special case of aggregation where the aggregated data consists of instances of types which all have a common base type. In the case of our simple graphical example we can imagine that a picture is an aggregation of many shapes, where each shape is an instance of a type derived from the Shape type.
This section defines the mechanisms for referencing data and domain values within FpML compliant documents.
Since the release 1.0 of the Architecture Specification there have been changes to these mechanisms which allow greater use of the validation provided by an XML parser. Code written to process references will need minor changes as a result.
An FpML document, such as a swap trade confirmation comprises product and reference data in a single message. At various points within the product definition for such a message non-product data objects (e.g. counter-parties, locations, rates, etc.) are need to place the product data in the correct context.
Often the same non-product data is required in several times within the document. Two basic strategies can be applied to address the repetition, namely:
Repeat the whole of the data object every time it is required.
Include the data object definition once and use references subsequently
Simple repetition can lead to large XML documents, if the data object is either frequently repeated or if it requires a large number of tags to define. A reference requires less XML code than object repetition and ensures consistency as there is only ever one instance definition.
XML 1.0 provides a several reference mechanisms based on the use of URLs and ID/IDREF attributes. Support for these mechanisms is continued in XML schema and enhanced with additional validation.
Within an XML schema the style of reference available is determined by the grammatical construction used to define it. The following section look are specific types of reference and show how they should appear in a conforming FpML document.
An intra-document reference defines a link between data described in two different parts of the same document. The reference may refer to data defined either before or after the point of reference and the same data may be referred to many times.
To participate in an intra-document reference the target element MUST have an attribute named 'id' with a type ID. If the element is only referenced sometimes then this attribute MAY be made optional. A referencing element MUST declare an IDREF attribute to hold the corresponding ID value.
A validating XML parser will ensure that every IDREF made in the document is satisfied by an element with a corresponding ID value. If it cannot an error will be reported. It should be noted that the presence of a matching ID value does not guarantee that the reference is to the correct element (e.g. an IDREF supposed to match a list of business centers could actually reference a party if the wrong is present in the document) and some additional validation should always be applied.
As an aid to programmers DOM (Level 2) based XML parsers automatically index elements with ID attributes during processing allowing them to be quickly located in the resulting node tree (e.g. by means of a call to Document.getElementById).
At the time that the FpML 1.0 Architecture specification was written it seemed that the W3C XPointer and XLink would provide a solution to the definition of intra-document links. The final form of these standard provided to be use useful within the context of FpML than had been hoped and in FpML 3.0 use of XPointer/XLink was removed in favour of ID/IDREF.
In XPointer syntax a reference to an element by its ID value was encoded as '#value' (which is an abbreviation for a call to the XPointer function id('value')). The '#' character is invalid in the specification of an IDREF and must be removed when transforming an old instance document to a later version of the FpML grammar.
A FpML document MAY make reference to a data object specified outside the scope of the referencing document. Where such references are required they should be specified in the form of a URI. HTTP URLs are just one kind of URI that might be used for such a reference.
The opportunities to use inter-document references in 'Bank-to-Bank' (B2B) communications may be limited. For example they may not be practical in situations where a change to the content of the referenced document would affect the interpretation or valuation of the referencing document. It is likely that URIs for referenced information would have be include some time stamp or version identification as part of its definition.
Many of the data elements defined in the FpML grammar are restricted to holding a limited set of values. For example day count convention, option type, or currency code are all examples of data elements which have a finite set of 'legal' values. Such restricted sets of values are frequently referred to as domains, and an individual value with a set is a 'domain value'.
It is also important to note that some domains are more likely to be modified or extended than others and that the act of doing so may or may not affect the interpretation of the grammar and existing documents. The AWG suggests that domains can be further categorised as follows based on this behaviour:
Closed domains are those for which every possible value can be listed now and for which future change is extremely unlikely. Examples are days of the week or period modifier (e.g. day, week, month, etc.).
Controlled domains are those for which a change would affect the interpretation or processing of documents. Date roll conventions for example would be considered controlled as it is possible that new ones may be created in the future and the addition would require software change (e.g. for date calculation and pricing).
Open domains are those for which the set of active values is large and and constantly modifying. Although changes do not affect the interpretation of documents. Examples are currency, business center and party codes.
In the FpML 1.0 Architecture specification the use of enumerations was not endorsed by the AWG because in XML 1.0 with a DTD specified grammar they could only be applied to attribute values, and FpML does not allow business data to appear in attributes. An XML schema based grammar can apply enumerations to element values allowing the additional validation provided by them to be applied to FpML.
As a result a large number of the closed and controlled domains previously provided as schemes have been replaced with enumerations within the schema. If it becomes necessary to extend these definitions to accommodate new financial products then FpML will release a new version with a release number determined by the compatibility of the changes with previous releases.
The migration of the FpML grammar to XML schema allows the use of schema based enumerations for 'closed' and 'controlled' domains. For consistency every such domain SHOULD be defined as a simple type which is a restriction on the standard XML schema data type token.
Two naming conventions are used in conjunction with enumerated values in FpML, namely
Where an externally defined domain of values is being represented (e.g. BIC codes, SWIFT location codes, ISO currency codes, etc.) the naming convention of the source is used.
Where the domain has been created by the FpML schema designers the domain values SHOULD use UpperCamelCase.
For example the following XML fragment shows how the enumeration type for the compounding method domain is defined.
<xsd:simpleType name="CompoundingMethodEnum">
<xsd:annotation>
<xsd:documentation source="http://www.FpML.org" xml:lang="en">The compounding calculation method</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="xsd:token">
<xsd:enumeration value="Flat">
<xsd:annotation>
<xsd:documentation source="http://www.FpML.org" xml:lang="en">Flat compounding. Compounding excludes the spread. Note that the first compounding period has it's interest calculated including any spread then subsequent periods compound this at a rate excluding the spread.</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="None">
<xsd:annotation>
<xsd:documentation source="http://www.FpML.org" xml:lang="en">No compounding is to be applied.</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="Straight">
<xsd:annotation>
<xsd:documentation source="http://www.FpML.org" xml:lang="en">Straight compounding. Compounding includes the spread.</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
</xsd:restriction>
</xsd:simpleType>
Domains which have been converted to enumerations in this manner no longer have any qualifying 'scheme' or 'schemeDefault' attributes.
Domains which are too large or too dynamic to be expressed as an enumeration remain supported as schemes (i.e. a combination of an identifying URI and a data value) in releases from FpML 4.0 although there are some modifications to their definition, namely:
A domain no longer has a schemeDefault attribute on the root FpML element.
Every scheme value reference MUST be qualified explicitly with a scheme URI on the referencing element.
If FpML defines a standard URI for a domain then its scheme attribute HAS a default value that MAY be overridden in the instance.
The URI for a scheme can be categorized as one of the following:
An external coding scheme, which has a well-known URI. In this case the URI is assigned by an external body, and may or may not have its own versioning and date syntax or semantics. The external body may be an open standards organization, or it may be a market participant.
An external coding scheme, which does not have a well-known URI. In this case FpML assigns a URI as a proxy to refer to the concept of the external scheme, but this URI will not be versioned or dated.
An FpML defined coding scheme. In this case the scheme is fully under FpML control and the URI will change reflecting newer versions and revisions as the scheme evolves and changes.
For the last two categories, the URI is FpML defined. Incorporating a date with the URI name allows for changes in the coding scheme without having to release a new FpML model.
For example, the MessageId type used in the definition of the FpML message header MUST always contain a user specified scheme URI as the generation of such identifiers varies from company to company.
<xsd:complexType name = "MessageId">
<xsd:annotation>
<xsd:documentation xml:lang = "en">The data type use for message identifiers.</xsd:documentation>
</xsd:annotation>
<xsd:simpleContent>
<xsd:extension base = "xsd:normalizedString">
<xsd:attribute name = "messageIdScheme" use = "required" type = "xsd:anyURI"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
By comparison the domain for party identifiers is defaulted to the FpML proxy for BIC codes and is defined as follows.
<xsd:complexType name = "PartyId">
<xsd:simpleContent>
<xsd:extension base = "normalizedString">
<xsd:attribute name = "partyIdScheme" default = "http://www.fpml.org/ext/iso9362" type = "anyURI"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
The use of explicit scheme URIs could make FpML documents significantly larger but in practice only a few institution specific schemes must always be qualified in a each document. The majority of frequently occurring scheme values have an associated FpML default scheme URI and the document will only be made larger these defaults are explicitly overridden.
The task of validating a scheme value falls on the document processing application rather than the XML parser as it may require access to data files or data bases which are implementation specific.
This change combined with the switch to enumerations has eliminated all the attributes from the FpML root element with the exception of the version number specification. It allows schema extenders to reference new domains without the need to modify the root element (to add a default for each new scheme) and it ensures that an instance contains all the scheme URIs it needs.
An additional benefit for message processing is that portions of an input message maintain their interpretation when copied into a new XML document, such as occurs in message processing where a result often contains elements (and their sub-elements) copied from an earlier request.
The FpML conventions regarding the use of namespaces have changed as part of the transition to XML schema. This section describes the reason for this change and design rules to be applied to FpML 4.0 and beyond.
The FpML 1.0 Architecture specification states clearly and succinctly that 'FpML 1.0 does not use namespaces'. This decision was taken because the W3C XML 1.0 recommendation allows a DTD based XML parser to be either namespace aware or non-namespace aware.
This distinction affects the processing of prefixed elements during parsing. A namespace aware parser sees the element <x:y> as consisting of a namespace prefix 'x' and a local element 'y', whilst a non-namespace aware parser sees the whole thing as the local element name 'x:y'. This makes the definition of the grammatical rules used for validation complex because they must be defined without prefixes for a namespace aware parser and containing prefixes for the non-namespace aware.
There are examples of DTD based grammars where entities are used within the DTD grammar rules to expand into the prefix or an empty string to get around this problem but they would have made the already complex FpML grammar even more difficult to understand, so in the FpML 1.0 Architecture the decision was made to opt for a grammar without namespaces that would have the same definition and interpretation regardless of the capabilities of the parser.
XML Schema are inherently dependent on namespaces. To define a schema you must reference the schema grammar itself through is namespace (e.g. http://www.w3.org/2001/XMLSchema). Similarly an instance document refers its defining schemas and the schema instance definitions (e.g. http://www.w3.org/2001/XMLSchema-instance) through namespaces.
Unlike the W3C XML 1.0 recommendation for behaviour of namespaces in XML schema based documents is consistently defined for all parsers. Hence in our position with regard to namespaces in FpML documents is reversed in this FpML 2.0 Architecture Specification for XML Schema based documents.
The spirit of namespaces is to avoid name collisions. By avoiding name collisions elements, attributes and types from multiple schemata can be mixed in a single XML document instance. The namespace mechanism works by assigning a global identifier, known as the namespace URI, to specify the schema, which is then associated with elements as they are used.
This association is done by an arbitrary namespace prefix that is chosen by the author of the XML document. This prefix enables the author to associate the URI with an element, attribute or type whenever they are used. As the URI is in turn associated with a schema, the author is in effect, borrowing the semantics of that original element. By adding the notion of a default namespace, the XML can also remain relatively non-verbose; i.e. some prefixes can be removed.
As FpML grows we believe that it will need to use an increasing number of namespaces to prevent naming collisions between definitions for different products and/or business processes. This in turn will mean an increased use of prefixes throughout instance documents.
URIs are used in a number of different situations, namely:
To identify standard XML Schema related definitions.
To identify the FpML content model (and in the future possibly sub-components of the content model).
To reference schemes defined outside of the FpML grammar.
Where FpML uses a component outside of its control (e.g. XML Schema itself, digital signatures, etc.) the URI defined for that component by its controlling organisation is used as is. For other FpML controlled components the URIs are defined according to the rules defined in the following sections.
The URI convention adopted for naming the FpML schema itself is based on the W3C naming for XML Schema and is based on a initial 'http:' prefix for the FpML organisation followed by the year of release, an optional component name and the release version as show below.
http://www.fpml.org/YEAR/FpML[-COMPONENT]-VERSION
Given this definition the URI that will be used to reference FpML 4.0 will be as follows:
http://www.fpml.org/2003/FpML-4-0
The optional component part of the URI is reserved for future use.
The FpML 1.0 Architecture specification defines the structure of FpML controlled URIs as having six parts.
http://www.fpml.org/AAA/BBBB/CCCC-DDD-EEEE-EE-EE
The components of this URI are defined as follows:
The protocol and server identifier. FpML 1.0 and 2.0 Architecture compliant documents use "http://www.fpml.org".
A marker string, "AAA" in this example. This is "spec" for FpML issued specifications and "ext" for external schemes that are assigned and FpML URI because they do not have an externally defined URI of thier own. Additional markers may be introduced in the future.
An optional year, "BBBB", to help manage documents. This mechanism is used quite widely in the W3C.
A string, "CCCC", indicating the name of the particular document. The field consists of lower case letters and numbers. Minus signs ('-') can also be used, except for the initial or final character.
The version, "DDD", indicates the version of the document. The field contains European digits. Minus signs ('-') can also be used, except for the initial or final character, to separate the major and minor parts. No part of the version number should contain more that 3 digits.
An optional date, "EEEE-EE-EE", in "year-month number-day number" format. To be consistent with W3C practices, a date is required for re-issues, and optional for new specifications. Note that re-issues are situations where the version is not changed. A URI without a date refers to the latest re-issue. In general you should use the form of the URI without the date when referring to a document. For example URIs embedded in FpML compliant documents should not include the re-issue date. The form with a date exists to allow release notes and revision histories to refer to specific documents.
Note that URIs do not necessarily resolve to physical resources. However, FpML SHOULD provide files that correspond to the http://www.fpml.org/spec URIs.
As examples:
http://www.fpml.org/spec/FpML-arch-2-0
represents the FpML 2.0 Architecture specification.
http://www.fpml.org/spec/2003/FpML-arch-2-0-2003-11-24
represents a specific re-issue of the specification.
http://www.fpml.org/ext/iso4217
is the FpML assigned URI for the external coding scheme defined by the ISO 4217 specification.
http://www.fpml.org/spec/business-day-convention-1-0
is the URI for an FpML defined coding scheme.
http://www.fpml.org/2003/FpML-4-0
represents the latest release of the FpML 4.0 grammar.
As was noted in the first version of the FpML Architecture specification, FpML is a living standard, evolving with time for a number of reasons, including:
Support for new types of financial product.
New roles for the FpML standard.
Advances in XML, in particular schemas.
Evidence of these changes can be seen in the FpML 2.0, 3.0 and 4.0 releases. The standard has expanded to encompass new derivative products (e.g. foreign exchange, equity derivatives, credit derivatives, etc.), has started to define business process specific messaging and from release 4.0 onwards the normative definition of the grammar will be in XML schema.
Version identification is part of the overall strategy for evolving FpML and potentially supporting interoperability between versions.
The FpML 1.0 Architecture specification established the requirement that an FpML document must explicitly indicate which version of the FpML standard it adheres to.
In DTD based documents the association between the instance and a specific version of the FpML was made through a public identifier contained within a DOCTYPE statement. This public identifier contained the FpML release number, for example:
<!DOCTYPE FpML PUBLIC "-//FpML//DTD Financial product Markup Language 1-0" "fpml-1-0.dtd">
In XML schema the equivalent association is made by referencing the standard FpML namespace from the FpML element via an 'xmlns' attribute.
In addition to the namespace reference the FpML element should also have a version attribute matching the version implemented by the grammar (e.g. "4-0").
The following shows a fully defined FpML element containing both FpML namespace as version attribute as well as the definitions required for XML schema and the FpML messaging framework.
<FpML xmlns:xsi="http://www.w3c.org" xmlns="http://www.fpml.org/2003/FpML-4-0" version="4-0" xsi:type="MessageType"> ... </FpML>
The following standards apply to FpML Architecture 2.0 compliant schemata.
An FpML namespace MAY be implemented as small number of modular component XML Schemas.
The main XML Schema for the FpML namespace SHOULD include (directly or indirectly) all the component schemas that comprise the namespace.
Each component XML Schema has an assocated version number (e.g. in its filename). In any release of FpML the main XML Schema MUST change and some of the component XML Schemas MAY also change. Where a component XML Schema does not change, its version my be left unchanged.
The overall FpML standard follows a single release cycle specified by a single version string. Individual parts of the FpML XML Schema cannot change between releases of FpML as a whole.
The granularity of FpML versioning is based on the modularity of the FpML XML Schema. Every release of the FpML standard will involve assigning a new version to the FpML XML Schema and any component Schemas that have changed. FpML documents must use the new public URI created by this process to access the new features of the grammar.
Each FpML grammar is defined to accept only a specific set of version numbers. To date the changes between each version have been such that each release has been incompatible with the last and only major version changes have occured so each schema has only accepted a single value. As the schema becomes increasingly stable it is likely that more minor releases of FpML will be produced which are entirely backwards compatible. In this case a schema my be defined to accept one of several version numbers (e.g. 4-0 or 4-1) and validation rules may be defined to prevent the use of a new feature with an old version number.
External standards have their own versioning methodology. For example, FpML uses ISO currency code. In this standard currency codes may be added or removed from day to day without any change to the version number. FpML does not lock the standard. In turn, new ISO currency codes can be used without requiring a new release of FpML.
Where possible, every attempt should be made to keep changes to the FpML schema as backwards compatible as possible. In general, the loosening of restriction, or the adding of new optional elements is backwards compatible.
For example, adding a completely new financial product in the form of a new substitutable element to the schema will not affect any existing products and the model is backwards compatible with previous releases.
A processor of XML that is designed to interpret an FpML document of one major version number is not in general able to correctly interpret FpML of any other major version. A transformation or re-designed processor would be required.
Minor version numbers, possibly using multiple levels, should be used where it is appropriate to relax this requirement. As an illustration (not a recommendation), a version 2-5 processor might, with no extra code, accept versions 2-0 through 2-2-0.
Users of FpML should be aware that the numbers of the levels of versioning might change from version to version, so the version after "2-1" may be "2-2-0".
In practice we expect version numbers to only have a major and a single level of minor version, for example 1-0 or 2-35. If FpML is versioned by a more complex scheme than this the a description of the rationale for each of the minor levels should be given.
This section looks at how the FpML implementers can extend or modify the core FpML grammar to suit their own purposes.
FpML follows an open standards development process based on producing a concensus view of financial products and business processes. Often an implementer requires features that are not yet included within the standard, for example additional products or additional details related to specific product variants. In these circumstances the implementer may be forced to consider extending the FpML grammar itself to include these additional features.
The XML DTDs used by FpML up to release 3.0 offered little support for extension and had to be manually changed to add new model components. This approach made it difficult and time consuming to migrate the changes when updates occurred to the core schema. With the introduction of XML Schema it becomes possible to take a different approach where user extensions can be kept separate from the core schema and may be more easily migrated to new releases.
The examples in this section are based on two XML techniques, namely:
Where the existing FpML grammar is being constrained (to eliminate parts of the grammar or reduce domain value choices) schema redefinition will be used. To implement such redefinitions a new schema module is required that will import and redefine components of the core schema but leave them in the same namespace.
Instance documents are not affected by the creation of such a module, all that is required is a suitable mapping in the XML parsers entity resolver to map the system identifier to the filename of the redefining schema module.
Where the existing FpML grammar is being expanded we will add the new definitions to a new namespace and use either substitution groups or type substitution to introduce new definitions into instance documents.
To make use of such an extension the instance document will have to include a declaration for the new namespace and such a document would fail validation if processed by an application that is unaware of the extensions.
The XML definitions to implement the extensions in this section are included in two example schemas distributed with this specification. The file 'fpml-acme-4-0.xsd' contains the redefined components whilst 'acme-1-0.xsd' contains extensions. The example instance documents use the 'schemaLocation' attribute to identify these files for the benefit of standard XML Schema and instance document editors in the absence of a properly configured entity resolver.
This section shows how a new product can be added to the FpML grammar in a new institution specific namespace. To create a new product two key definitions are required, namely:
A new complex type is need to define the content model for the new product. This type MUST be derived from the base FpML type 'Product' either directly or indirectly via another FpML product type (e.g. Swap, FxLeg, etc.). The content model may be defined by referencing existing FpML component type or by defining new components (in the new namespace).
A new global element MUST be defined which takes its content model from the new product type and which can substitute for the FpML global element 'product'.
The following schema shows the two definitions necessary to create a basic product type, in this case an 'AcmeOption', although no specific content model has been added to keep the example brief.
<xsd:schema xmlns = "http://www.acme.com/2003/AcmeML-1-0"
targetNamespace = "http://www.acme.com/2003/AcmeML-1-0"
xmlns:fpml = "http://www.fpml.org/2003/FpML-4-0"
xmlns:xsd = "http://www.w3.org/2001/XMLSchema"
elementFormDefault = "qualified"
attributeFormDefault = "unqualified">
<xsd:import namespace = "http://www.fpml.org/2003/FpML-4-0"
schemaLocation = "fpml-main-4-0.xsd"/>
<!-- The new Product type -->
<xsd:complexType name = "AcmeOption">
<xsd:complexContent>
<xsd:extension base = "fpml:Product">
<xsd:sequence>
<xsd:element name = "someData" type = "xsd:normalizedString"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<!-- The new product element -->
<xsd:element name = "acmeOption" type = "AcmeOption" substitutionGroup = "fpml:product"/>
</xsd:schema>
To use this new product in an FpML message or data document the Acme namespace must be defined and given a prefix (e.g. acme) allowing its definitions to referenced as required.
<FpML version="4-0" xsi:type="DataDocument"
xmlns="http://www.fpml.org/2003/FpML-4-0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:acme="http://www.acme.com/2003/AcmeML-1-0"
xsi:schemaLocation="http://www.fpml.org/2003/FpML-4-0 fpml-acme-4-0.xsd
http://www.acme.com/2003/AcmeML-1-0 acme-1-0.xsd">
<trade>
<tradeHeader>
<partyTradeIdentifier>
<partyReference href="CITI"/>
<tradeId tradeIdScheme="http://www.citi.com/fx/trade-id">CITI123</tradeId>
</partyTradeIdentifier>
<partyTradeIdentifier>
<partyReference href="BARC"/>
<tradeId tradeIdScheme="http://www.barclays.com/fx/trade-id">BARC987</tradeId>
</partyTradeIdentifier>
<tradeDate>2001-10-23</tradeDate>
</tradeHeader>
<acme:acmeOption>
<acme:someData>Real Data Content would go here</acme:someData>
</acme:acmeOption>
</trade>
<party id="CITI">
<partyId partyIdScheme="http://www.fpml.org/ext/iso9362">CITIUS33</partyId>
</party>
<party id="BARC">
<partyId partyIdScheme="http://www.fpml.org/ext/iso9362">BARCGB2L</partyId>
</party>
</FpML>
The procedure for creating a new message type is similar once the appropriate base message type (e.g. 'RequestMessage', 'ResponseMessage' or 'NotificationMessage') has been selected. The designer must derive the new message type from the base and add an appropriate content model. Again the content model can comprise of elements defined from existing FpML types or new ones from the new namespace.
<xsd:schema xmlns = "http://www.acme.com/2003/AcmeML-1-0"
targetNamespace = "http://www.acme.com/2003/AcmeML-1-0"
xmlns:fpml = "http://www.fpml.org/2003/FpML-4-0"
xmlns:xsd = "http://www.w3.org/2001/XMLSchema"
elementFormDefault = "qualified"
attributeFormDefault = "unqualified">
<xsd:import namespace = "http://www.fpml.org/2003/FpML-4-0"
schemaLocation = "fpml-main-4-0.xsd"/>
<!-- A new message type -->
<xsd:complexType name = "AcmeMessage">
<xsd:complexContent>
<xsd:extension base = "fpml:RequestMessage">
<xsd:sequence>
<xsd:element name = "someData" type = "xsd:normalizedString"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:schema>
The messaging framework uses type substitution in the <FpML> root element to reference the new content model for the document as a whole.
<FpML version="4-0" xsi:type="acme:AcmeMessage"
xmlns="http://www.fpml.org/2003/FpML-4-0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:acme="http://www.acme.com/2003/AcmeML-1-0"
xsi:schemaLocation="http://www.fpml.org/2003/FpML-4-0 fpml-acme-4-0.xsd
http://www.acme.com/2003/AcmeML-1-0 acme-1-0.xsd">
<header>
<messageId messageIdScheme="http://www.ibm.com/2003/MessageId">2435/GQW</messageId>
<sentBy>IBM</sentBy>
<sendTo>ISDA</sendTo>
<creationTimestamp>2003-11-21T10:46:00-00:00</creationTimestamp>
</header>
<acme:someData>Real data content here</acme:someData>
</FpML>
The FpML type PartyTradeInformation allows the trader(s) associated with a trade to be captured. This example extends this definition to show how additional internal information could be added.
The first stage in creating this extension is the definition of an extended PartyTradeInformation type in a namespace which includes the additional elements required. The following shows how this definition is created.
<xsd:schema xmlns = "http://www.acme.com/2003/AcmeML-1-0"
targetNamespace = "http://www.acme.com/2003/AcmeML-1-0"
xmlns:fpml = "http://www.fpml.org/2003/FpML-4-0"
xmlns:xsd = "http://www.w3.org/2001/XMLSchema"
elementFormDefault = "qualified"
attributeFormDefault = "unqualified">
<xsd:import namespace = "http://www.fpml.org/2003/FpML-4-0"
schemaLocation = "fpml-main-4-0.xsd"/>
<!-- An extended version of PartyTradeInformation -->
<xsd:complexType name = "PartyTradeInformation">
<xsd:complexContent>
<xsd:extension base = "fpml:PartyTradeInformation">
<xsd:sequence>
<xsd:element name = "tradingSystem" type = "xsd:normalizedString" minOccurs = "0"/>
<xsd:element name = "salesPerson" type = "xsd:normalizedString" minOccurs = "0"/>
<xsd:element name = "tradeAccount" type = "xsd:normalizedString" minOccurs = "0"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:schema>
In order to use this extension it must be made accessible to the instance document by means of an additional namespace definition and referenced as a type substitution on the appropriate element.
<FpML version="4-0" xsi:type="DataDocument"
xmlns="http://www.fpml.org/2003/FpML-4-0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:acme="http://www.acme.com/2003/AcmeML-1-0"
xsi:schemaLocation="http://www.fpml.org/2003/FpML-4-0 fpml-main-4-0.xsd
http://www.acme.com/2003/AcmeML-1-0 acme-1-0.xsd">
<trade>
<tradeHeader>
<partyTradeIdentifier>
<partyReference href="CITI"/>
<tradeId tradeIdScheme="http://www.citi.com/fx/trade-id">CITI123</tradeId>
</partyTradeIdentifier>
<partyTradeIdentifier>
<partyReference href="BARC"/>
<tradeId tradeIdScheme="http://www.barclays.com/fx/trade-id">BARC987</tradeId>
</partyTradeIdentifier>
<partyTradeInformation xsi:type="acme:PartyTradeInformation">
<partyReference href="CITI"/>
<trader>John Doe</acme:trader>
<acme:salesPerson>Jane Doe</acme:salesPerson>
</partyTradeInformation>
<tradeDate>2001-10-23</tradeDate>
</tradeHeader>
<fxSingleLeg>
<exchangedCurrency1>
<payerPartyReference href="BARC"/>
<receiverPartyReference href="CITI"/>
<paymentAmount>
<currency currencyScheme="http://www.fpml.org/ext/iso4217-2001-08-15">GBP</currency>
<amount>10000000</amount>
</paymentAmount>
</exchangedCurrency1>
<exchangedCurrency2>
<payerPartyReference href="CITI"/>
<receiverPartyReference href="BARC"/>
<paymentAmount>
<currency currencyScheme="http://www.fpml.org/ext/iso4217-2001-08-15">USD</currency>
<amount>14800000</amount>
</paymentAmount>
</exchangedCurrency2>
<valueDate>2001-10-25</valueDate>
<exchangeRate>
<quotedCurrencyPair>
<currency1 currencyScheme="http://www.fpml.org/ext/iso4217-2001-08-15">GBP</currency1>
<currency2 currencyScheme="http://www.fpml.org/ext/iso4217-2001-08-15">USD</currency2>
<quoteBasis>Currency2PerCurrency1</quoteBasis>
</quotedCurrencyPair>
<rate>1.48</rate>
</exchangeRate>
</fxSingleLeg>
</trade>
<party id="CITI">
<partyId partyIdScheme="http://www.fpml.org/ext/iso9362">CITIUS33</partyId>
</party>
<party id="BARC">
<partyId partyIdScheme="http://www.fpml.org/ext/iso9362">BARCGB2L</partyId>
</party>
</FpML>
Some implementer may wish to exclude certain grammatical constructions from the FpML grammar. Such restrictions may serve to simplify a product making it impossible to specify certain features, like complex payment schedules. There are three ways in which we might choose to define such a constraints, namely:
If the intention is to exclude the use of some elements under very specific conditions (e.g. content allowed in one variety of interest rate swap but not in another) then a custom validation rule is the easiest way to implement its detection.
If the intention is to exclude the use of some elements from all locations in the model where its defining type is used then a schema redefinition is the simplest approach.
If the intention is to exclude the use of some elements in some areas of the model but not others then creating a new restricted type and using type substitution may be easiest.
The definition of validation rules is the remit of the FpML Validation Working Group (VWG) and is described in their specification. The other approaches can be handled through XML Schema definitions.
XML Schema redefinition allows a complex type to be redefined as a restricted subset of its own content and the resulting type is then used in place of its original definition throughout the entire schema.
The Swapswire service for example disallows the presence of the elements 'cancelableProvision' and 'extendibleProvision' within its definition of a swap. The removal of these elements can be performed from the XML schema for FpML 4-0 by directing the XML parser to the following definitions.
<xsd:schema xmlns="http://www.fpml.org/2003/FpML-4-0"
targetNamespace="http://www.fpml.org/2003/FpML-4-0"
xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"
attributeFormDefault="unqualified">
<!--
== Copyright (c) 2002-2003. All rights reserved.
== Financial Products Markup Language is subject to the FpML public license.
== A copy of this license is available at http://www.fpml.org/documents/license
-->
<xsd:redefine schemaLocation="fpml-main-4-0.xsd">
<!-- Redefine the Swap type to eliminate some elements -->
<xsd:complexType name="Swap">
<xsd:complexContent>
<xsd:restriction base="Swap">
<xsd:sequence>
<xsd:element name="productType" type="ProductType" minOccurs="0"/>
<xsd:element name="productId" type="ProductId" minOccurs="0" maxOccurs="unbounded"/>
<xsd:element name="swapStream" type="InterestRateStream" maxOccurs="unbounded"/>
<xsd:element name="earlyTerminationProvision" type="EarlyTerminationProvision" minOccurs="0"/>
<xsd:element name="additionalPayment" type="Payment" minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="id" type="xsd:ID"/>
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
</xsd:redefine>
</xsd:schema>
To override the content model of a type in just a few places within the FpML grammar we must create a new restricted type and use type substitution within the instance document to reference it. For example the following definition creates a new type 'MySwap' that has the same restrictions as the previous example.
<xsd:schema xmlns="http://www.fpml.org/2003/FpML-4-0"
targetNamespace="http://www.fpml.org/2003/FpML-4-0"
xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"
attributeFormDefault="unqualified">
<!--
== Copyright (c) 2002-2003. All rights reserved.
== Financial Products Markup Language is subject to the FpML public license.
== A copy of this license is available at http://www.fpml.org/documents/license
-->
<xsd:redefine schemaLocation="fpml-main-4-0.xsd">
<!-- perform redefinitions here -->
</xsd:redefine-->
<!-- Define a modified the Swap type in the FpML namespace -->
<xsd:complexType name="MySwap">
<xsd:complexContent>
<xsd:restriction base="Swap">
<xsd:sequence>
<xsd:element name="productType" type="ProductType" minOccurs="0"/>
<xsd:element name="productId" type="ProductId" minOccurs="0" maxOccurs="unbounded"/>
<xsd:element name="swapStream" type="InterestRateStream" maxOccurs="unbounded"/>
<xsd:element name="earlyTerminationProvision" type="EarlyTerminationProvision" minOccurs="0"/>
<xsd:element name="additionalPayment" type="Payment" minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="id" type="xsd:ID"/>
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
</xsd:schema>
The values of some FpML enumeration represent the superset of values used in all the supported products. A system that deals exclusively in a single product would expect to find only a subset of values in FpML formatted documents it receives.
By redefining an enumeration we can reduce the number of allowable values it will accept. For example the following XML Schema reduced the set of FpML business day conventions to just four.
<xsd:schema xmlns="http://www.fpml.org/2003/FpML-4-0"
targetNamespace="http://www.fpml.org/2003/FpML-4-0"
xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified" attributeFormDefault="unqualified">
<xsd:redefine schemaLocation="fpml-main-4-0.xsd">
<xsd:simpleType name="BusinessDayConventionEnum">
<xsd:annotation>
<xsd:documentation source="http://www.FpML.org"
xml:lang="en">This a subset of the conventions allowed by the normal FpML 4-0
grammar.</xsd:documentation>
</xsd:annotation>
<xsd:restriction base="BusinessDayConventionEnum">
<xsd:enumeration value="FOLLOWING">
<xsd:annotation>
<xsd:documentation source="http://www.FpML.org"
xml:lang="en">The non-business date will be adjusted to the first following
day that is a business day</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="MODFOLLOWING">
<xsd:annotation>
<xsd:documentation source="http://www.FpML.org"
xml:lang="en">The non-business date will be adjusted to the first following
day that is a business day unless that day falls in the next calendar month,
in which case that date will be the first preceding day that is a business
day.</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="PRECEDING">
<xsd:annotation>
<xsd:documentation source="http://www.FpML.org" xml:lang="en">The non-business
day will be adjusted to the first preceding day that is a business
day.</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="NONE">
<xsd:annotation>
<xsd:documentation source="http://www.FpML.org" xml:lang="en">The date will not
be adjusted if it falls on a day that is not a business
day.</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
</xsd:restriction>
</xsd:simpleType>
</xsd:redefine>
</xsd:schema>
Some implementations may wish to place additional constraints on certain FpML schemes to limit the range of acceptable values. Normally such constraints would be encoded within business validation logic applied after XML parsing has been completed but an alternative approach would be to add them to the FpML schema using a redefinition.
For example an electronic trading or brokerage system might limit its users to a subset on commonly traded currencies. This constraint can be added by creating a redefinition of the FpML type 'Currency' which adds an enumeration.
<xsd:schema xmlns="http://www.fpml.org/2003/FpML-4-0"
targetNamespace="http://www.fpml.org/2003/FpML-4-0"
xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified" attributeFormDefault="unqualified">
<xsd:redefine schemaLocation="fpml-main-4-0.xsd">
<!-- Add a restriction to the Currency scheme -->
<xsd:complexType name="Currency">
<xsd:simpleContent>
<xsd:restriction base="Currency">
<xsd:enumeration value="CAD">
<xsd:annotation>
<xsd:documentation>Canadian Dollar</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="CHF">
<xsd:annotation>
<xsd:documentation>Swiss Franc</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="DKK">
<xsd:annotation>
<xsd:documentation>Danish Krone</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="EUR">
<xsd:annotation>
<xsd:documentation>Euro</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="GBP">
<xsd:annotation>
<xsd:documentation>Sterling</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="JPY">
<xsd:annotation>
<xsd:documentation>Japanese Yen</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="NOK">
<xsd:annotation>
<xsd:documentation>Norwegian Krone</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="SEK">
<xsd:annotation>
<xsd:documentation>Swedish Krona</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="USD">
<xsd:annotation>
<xsd:documentation>U.S. Dollar</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:attribute name="currencyScheme"
default="http://www.fpml.org/ext/iso4217-2001-08-15"
type="xsd:anyURI"/>
</xsd:restriction>
</xsd:simpleContent>
</xsd:complexType>
</xsd:redefine>
</xsd:schema>
This section contains a set of frequently asked questions and answers directed at the Architecture Working Group.
Modifying the any of the schemas distributed by FpML is a really bad idea. Changes made to any one version of FpML in this manner will be difficult to migrate to later version.
A much better approach would be create your own XML Schema with its own namespace (based on your institutions name or standard website address) and use type substitution to mix components of the two schemas in your instance documents.
In XML Schema an enumeration is defined using a simple type declaration with a set of value restrictions, as shown in the following example.
<xsd:simpleType name = "BooleanLogic">
<xsd:restriction base = "token">
<xsd:enumeration value = "false"/>
<xsd:enumeration value = "true"/>
</xsd:restriction>
</xsd:simpleType>
Simple types may be derived from each other but only via restriction, which means that it possible to allow only a subset of the original enumerated values to be accepted, but it is impossible to add new choices.
One way to circumvent this problem is to define a new type which is the union of some base enumeration and a new anonymous type containing the additional values. The following definition shows how this can be applied to the previous example to create a type that accepts 'true', 'false' or 'maybe'.
<xsd:simpleType name = "FuzzyLogic">
<xsd:union memberTypes = "BooleanLogic">
<xsd:simpleType>
<xsd:restriction base = "token">
<xsd:enumeration value = "maybe"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:union>
</xsd:simpleType>
It is important to note that this new type is not 'type compatible' with the original enumeration (as it is not directly a restriction of it) and cannot be used to override the type of an existing enumerated element but it can be used to define new elements.
This section is a brief summary of the features of XML schema and describes some of the implications of their use. It is not intended to be a full tutorial on the subject but serves to highlight the rational behind some of the architectural choices.
Namespaces provide a mechanism for 'scoping' an identifier so that if the same name has been used by two or more schema designers then the specific context for an individual use can be determined. A namespace is identified by a unique URI. It may be a URL leading to the schema (e.g. via HTTP) but does not have to be, in which case the XML parser should use a custom EntityResolver class to map from the URN to a physical URL or file location.
When designing a schema there are three choices for the designer that will affect how easy it is to design and work with, both from their perspective and from that of someone wishing to combine the core schema with their own extensions.
Have no namespace at all.
A schema (and its constituent sub-schemata) may be defined without associating it to any namespace at all. Such a schema may be included into another schema in which case it takes on the namespace (if any) of the extending schema . The core schema designer must ensure that all element and type identifiers are unique within his schema.
As the core schema has no namespace to qualify the element and type identifiers the designers of any extending schema must also avoid naming clashes by design. If the core schema is modified then it may inadvertently create a name clash with a definition in the extending schema making the taking up of new version problematic.
Without a namespace it is not possible for instance documents to reference the schema, they can only be used as components to construct other XML Schemas.
Have one namespace.
The schema (and its constituent sub-schemata) can be defined as belonging to a single target namespace. Again the core schema designer must ensure by design that there are no name clashes within the schema. An extending schema may reuse any of the identifiers without fear of name collision, although prefixes will be need to be used in an instance document to indicate which definition is actually in use.
When referenced from an instance document one of the schemas may be defined as the default namespace to avoid identifier prefixes (e.g. the core schema) but any others must use prefixes (e.g. the extensions).
Have more than one namespace.
A schema could be broken into a number of separate areas (e.g. product types, business processes, reference data type, etc) each with its own namespace and interconnected by imports. Identifiers used in any namespace may be redefined in another or in an extending schema without name collision.
Whilst an instance document could assign the default namespace to one component of the overall schema it is more likely (for consistency) that prefixes would be assigned to all referenced schemata and every element/type prefixed to indicate its origin. To date the format of an FpML instance document has been kept simple and free of namespace prefixes. To maintain this position going forward FpML would have to either use no namespaces or a single namespace. Having no namespace would make proprietary extensions awkward to maintain as a change in the core schema could collide with an extension. Having a single namespace would mean that prefixes would only be needed whenever an extension is invoked, making them easy to identify within the document.
Definitions within an XML schema may either be defined 'globally' at the outermost level of the schema or 'locally' within another definition.
Only global definitions may be referenced from within other definitions.
Only global elements may be used as the target of a substitution group.
Only global elements may be used at the root for an instance document.
Local definitions may reuse an identifier but assign new content.
XML schemas are commonly classified into one of three (bizarrely) named groups according to how they use global and local definitions, namely:
Salami Sliced
A schema consisting of predominately global definitions.
Venetian Blind
A schema in which consists of global types and local elements (except for the root element).
Russian Doll
A schema in which definitions are predominately local and follow a similar structure to the instance documents.
Using global scoping establishes consistency throughout a schema although such general definitions may become too generic for some circumstances, needing additional semantic validation in the processing application. A local definition can avoid some of the generality by allowing the content to model the exact usage but such definitions cannot be used in conjunction with other features such as substitution groups or type derivation.
Elements and attributes defined with global scope belong to the schema's target namespace.
Elements and attributes defined with local scope will have either the schema's target namespace or no namespace, depending on the setting of the schema's 'elementFormDefault' and 'attributeFormDefault' attributes or their local overriding settings.
In most cases the setting of these 'form' values has little impact on the XML Schema or its instance documents, but significantly it does affect the ease with which restriction between complex types can be performed.
Attributes provide simple containers for data values associated with elements. Attributes are single values and cannot appear more than once per element. It is not possible to define any relationships between attributes or the order in which they are defined.
A set of attributes that appear commonly together throughout a schema can be collected into a re-useable attribute group definition and referenced as needed from other content definitions.
Elements provide the main structural compents for document markup. They may be associated with a simple type (e.g. a single value), a complex type (e.g. a structure containing sub-elements in a particular order), or a mixture of the two (e.g. text intermixed with structured content).
The type of an element my be defined elsewhere in the schema and referenced (as in the following examples) or defined 'anonymously' as part of its definition. Such anonymous definitions have no name and cannot be referenced elsewhere in the schema.
<!-- Some simple global element definitions --> <xsd:element name = "elementA" type = "xsd:string"/> <xsd:element name = "elementB" type = "xsd:date"/> <xsd:element name = "elementC" type = "MyType"/>
A set of elements that appear commonly together throughout a schema with the same cardinalities can be collected into a re-useable model group definition and referenced as needed from other content definitions.
<!-- A model group with a local element definition -->
<xsd:group name = "groupOne">
<xsd:sequence>
<xsd:element ref = "elementA"/>
<xsd:element name = "elementD" type = "xsd:string"/>
</xsd:sequence>
</xsd:group>
<!-- A model group simulating inheritance by extension -->
<xsd:group name = "groupTwo">
<xsd:sequence>
<xsd:group ref = "groupOne"/>
<xsd:element ref = "elementB"/>
<xsd:element ref = "elementC"/>
</xsd:sequence>
</xsd:group>
The content of a model group can consist of local element definitions and references to global element definitions as well as references to other groups. This last feature creates content that resembles the action of 'inheritance by extension' (described later), or if many model groups are referenced, 'multiple inheritance'.
Model groups function similarly to 'parsed character entities' like those used through out the FpML 1.0, 2.0 and 3.0 DTDs (e.g. FPML_Money, etc.).
Substitution groups provide a mechanism for defining replacements for a global element that may be used anywhere within an instance document wherever the original element was valid. The substituting element must be type compatible with the original (e.g. either an extension or restriction of the same base type).
Substitution groups are commonly used to as a mechanism for extending a schema by provide a set of 'attachment points' and associated base types from which extensions are derived.
The use of substitution groups forces the use of global element definitions for elements that may be replaced and those that do the replacing.
XML schema provides two different kinds of data-types, namely simple (single valued) types and complex (multi-valued) types, and some mechanisms for deriving them from existing definitions.
Derivation by extension is only allowed between complex types. The derived type will inherit the content model of the parent (e.g. a sequence of elements) to which it can then append an additional sequence of elements.
Derivation by restriction is allowed for both simple and complex types. Restriction produces a new type that will accept a subset of the content that will be accepted by the parent type.
In the case of a simple type restrictions are defined by modifying facets such as minimum/maximum values or by applying regular expressions. For complex types the restriction is defined by modifying element types or changing their cardinality (e.g. increasing the minimum cardinatlity to make an optional element mandatory or reducing the maximum cardinality to remove an optional element altogether).
XML instance documents may override the type of an element by substituting a new type for the value declared in the schema. In order to be eligible for type substitution the new type must be derived from the original type either directly or indirectly via some other intermediate types.
XML Schema provides support for validating the integrity of keys used to identify business objects and the references between them. The following sections look briefly at these facilities.
A business object normally has a set of values which serve to create an identifier for the object as a whole. Usually such an identifier must be different each business object of a given type so that an object can be unambiguously referenced. XML Schema provides a facility for defining the element and attribute values that comprise the key for a business object and ensures during parsing that each key is defined only once.
The definition of each unique key must be placed within element that will contain the business objects to be validated. For example should it be necessary to redefine the validation provided by the XML parser for ID attributes, then it could be defined for a single 'id' attribute as follows:
<xsd:element name = "FpML">
<xsd:unique name = "partyId" >
<xsd:selector xpath = ".//party"/>
<xsd:field xpath = "@id"/>
</xsd:unique>
</xsd:element>
XML Schemas, and DTDs before them, provide a facility for creating references between instance document sections through the use of ID and IDREF attributes. A validating XML parser ensures that each ID value in the instance document is unique and that every IDREF value appears as an ID somewhere in the document, but this simple mechanism by itself does not ensure that the ID is associated with the right kind of element.
The addition of keys and key references in XML schema is an attempt to detect and prevent such referential errors. For example the following changes to the FpML schema would prevent a party reference referring to anything other than a valid party instance.
<xsd:element name = "FpML">
<xsd:key name = "partyKey" >
<xsd:selector xpath = ".//party"/>
<xsd:field xpath = "@id"/>
</xsd:key>
<xsd:keyref name="partyReferenceFK1" refer ="partyKey">
<xsd:selector xpath = ".//partyReference"/>
<xsd:field xpath = "@href"/>
</xsd:keyref>
</xsd:element>
The use of substitution groups within a schema can determine whether keys and keyrefs can be used to validate all intra-document references. For example in the current FpML schema a substitution group is used together with an abstract element (e.g. '<product>') to provide an extension point for financial products (e.g. '<swap>', '<fra>', etc.).
If the key and keyref definitions where defined as in the previous party example with the XPath expression in the product key being defined as ".//product" then no reference to a product would pass validation as the instance documents contain a substituted element (e.g. '<swap>', '<fra>', etc.) rather than '<product>' so no match against the XPath could ever be found.
Changing the XPath to include alternative elements (e.g. './/swap | .//fra | ...') would allow it to match against substitutions known to the FpML schema designers but would not match against extensions created by implementers (e.g. '<acme:widgetSwap>) unless they edit the core schema to add their elements to the expression.
This issue does not exist if type substitution is used in preference to substitution groups as the mechanism for extension (e.g. '<product xsi:type="acme:WidgetSwap">) and would simplify the specification of references. However this represents a departure from the approach taken to date.