FpML Architecture Specification 2.2 Trial Recommendation 6 May 2010

This version: http://www.fpml.org/spec/fpml-arch-2-2-tr-1

Latest version: http://www.fpml.org/spec/fpml-arch-2-2-tr-1

Previous version: http://www.fpml.org/spec/fpml-arch-2-2-wd-1/

 

Document built: Thu 2010/05/06 19:01:52

Copyright (c) 1999 - 2010 by INTERNATIONAL SWAPS AND DERIVATIVES ASSOCIATION, INC.

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.html




The FpML specifications provided are without warranty of any kind, either expressed or implied, including, without limitation, warranties that FpML, or the FpML specifications are free of defects, merchantable, fit for a particular purpose or non-infringing. The entire risk as to the quality and performance of the specifications is with you. Should any of the FpML specifications prove defective in any respect, you assume the cost of any necessary servicing or repair. Under no circumstances and under no legal theory, whether tort (including negligence), contract, or otherwise, shall ISDA, any of its members, or any distributor of documents or software containing any of the FpML specifications, or any supplier of any of such parties, be liable to you or any other person for any indirect, special, incidental, or consequential damages of any character including, without limitation, damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses, even if such party shall have been informed of the possibility of such damages.



Table Of Contents

    1 Introduction
        1.1 Changes compared to Architecture 2.1
        1.2 Changes compared to Architecture 2.0
        1.3 Changes compared to Architecture 1.0
             1.3.1 Intra-Document links
             1.3.2 Migration to XML schema
                 1.3.2.1 Local Element Definition
                 1.3.2.2 Enumerations
                 1.3.2.3 Embedded Annotation
                 1.3.2.4 eCore Annotations
             1.3.3 Migration to Messaging
             1.3.4 Changes to Schemes
        1.4 A word on Schema design 'Best Practice'
        1.5 Future Work
             1.5.1 More Namespaces
             1.5.2 Enhanced Validation
    2 Content Model
        2.1 Primitive Data Types
             2.1.1 date & dateTime
        2.2 Naming Conventions
             2.2.1 lowerCamelCase
             2.2.2 UpperCamelCase
             2.2.3 Groups and Enumerations
             2.2.4 Definitions and References
             2.2.5 Naming Anomalies
        2.3 XML Schema Design Rules
             2.3.1 Qualification
             2.3.2 File Structure
                 2.3.2.1 Circular Dependency
             2.3.3 Attributes
             2.3.4 Attribute Groups
             2.3.5 Elements
                 2.3.5.1 nillable
                 2.3.5.2 Substitution Groups
                 2.3.5.3 Type Substitution
             2.3.6 Model Groups
             2.3.7 Simple Types
             2.3.8 Complex Types
             2.3.9 Content Models
                 2.3.9.1 Sequential
                 2.3.9.2 Choice Groups
                 2.3.9.3 Ordering within Repetitions
                 2.3.9.4 Unordered Content
                 2.3.9.5 Mixed Content
                 2.3.9.6 Validation
             2.3.10 Boolean Values
             2.3.11 Scheme Values
             2.3.12 Annotation
             2.3.13 Deprecated Structures
                 2.3.13.1 Definition
                 2.3.13.2 Flag
        2.4 Object Oriented Idioms
             2.4.1 Types
                 2.4.1.1 Complex Content
             2.4.2 Inheritance
                 2.4.2.1 By Extension
                 2.4.2.2 By Restriction
             2.4.3 Abstract Types
             2.4.4 Arrays (Sequences)
             2.4.5 Association
             2.4.6 Aggregation
             2.4.7 Aggregation of Sub-Types
    3 References
        3.1 References to Objects
             3.1.1 Intra-Document
                 3.1.1.1 Differences compared to Architecture 1.0
             3.1.2 Inter-Document
        3.2 References to Values
        3.3 Enumerations
        3.4 Schemes
             3.4.1 Genericode
    4 Namespaces & URIs
        4.1 The Rationale of the 1.0 FpML Architecture
        4.2 Changes Introduced by XML Schema
        4.3 Namespaces in FpML 4.0 and beyond
        4.4 URI Recommendations
             4.4.1 URIs for FpML XML Schema
             4.4.2 URIs for FpML Schemes
                 4.4.2.1 Processing Scheme URIs
             4.4.3 URI Examples
    5 Versions
        5.1 Version Identification
        5.2 Modular XML Schema Structure
        5.3 XML Schema Versioning
        5.4 Versioning of External Entities
        5.5 Backwards Compatibility
        5.6 Major and Minor Versions
        5.7 Object Identification
             5.7.1 Principles
    6 Extending FpML
        6.1 Introduction
        6.2 Adding new Product
        6.3 Adding a new Message
        6.4 Extending Existing Content
        6.5 Restricting Existing Content
             6.5.1 Restricting Content Globally
             6.5.2 Restricting Content Locally
        6.6 Restricting an Enumeration
        6.7 Restricting a Scheme
    7 FAQ
        7.1 Can I add new features directly to the FpML Schemas?
        7.2 Why can't I extend an enumeration?
    8 W3C XML Schema - A Summary
        8.1 Namespaces
        8.2 Scoping
             8.2.1 Scoping and Namespaces
        8.3 Attributes
             8.3.1 Attribute Groups
        8.4 Elements
             8.4.1 Model Groups
             8.4.2 Substitution Groups
        8.5 Types
             8.5.1 Derivation by Extension
             8.5.2 Derivation by Restriction
             8.5.3 Type Substitution
        8.6 Integrity
             8.6.1 Uniqueness
             8.6.2 Keys & Key References

1 Introduction

The FpML Architecture Version 2.2 Specification defines that standards and principles on which the FpML grammatical definitions are based.

The FpML 2.2 Architecture builds upon the earlier FpML Architecture specifications 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.

1.1 Changes compared to Architecture 2.1

1.2 Changes compared to Architecture 2.0

1.3 Changes compared to Architecture 1.0

This section highlights the most significant changes that have been made to the architecture standards since the last release.

1.3.1 Intra-Document links

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.

1.3.2 Migration to XML schema

From FpML 4.0 the normative implementation of the FpML grammar will be represented as a set of XML schemas. The XML schema standard 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.

1.3.2.1 Local Element Definition

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>)

1.3.2.2 Enumerations

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.

1.3.2.3 Embedded Annotation

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.

1.3.2.4 eCore Annotations

The FpML 4.3 schemas have been enhanced with eCore annotations. eCore definitions provide additional information to schema processing applications, for example those written using the Eclipse Modelling Framework (EMF), to enable a simpler mapping between XML schema and UML models.

Only limited use of eCore has been made at this time, primarily to identify the type of the target business object referenced by an IDREF attribute. FpML may make greater use of eCore in the future. The presence of the annotations does not interfere with normal XML schema parsing.

1.3.3 Migration to Messaging

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.

1.3.4 Changes to Schemes

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.

1.4 A word on Schema design 'Best Practice'

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:

1.5 Future Work

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.

1.5.1 More Namespaces

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.

1.5.2 Enhanced Validation

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.

2 Content Model

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:

Additional information on XML schema and its usage can be found in this associated document:

2.1 Primitive Data Types

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:

2.1.1 date & dateTime

The global nature of the finance industry means that under some circumstances it may be important to take into account time difference between the producer and consumer of FpML documents. For example a trade negotiated between parties in Sydney and San Francisco may appear to have two different trade dates when sent to matching service. Similar issues occur internally when trades negotiated in one geographic region are transmitted to another for processing and settlement.

The XML schema datatype for date and datetime values allow the inclusion of a time duration expressing the difference between local time and UTC (e.g. 2006-07-06+05:00). The time duration can be an hours and minutes value (e.g. hh:mm) up to plus or minus 14 hours from UTC.

The XML schema specification datatype section contains a description of how date and datetime values should be compared, taking into account their time duration offsets. These rules are implemented as part of XPath 2.0.

The AWG recommends that document creators be consistent and either generate a time duration offset on all date and dateTime values in an instance or none at all. Documents MUST not contain a mixture of values with and without time duration offsets. Processors of FpML documents MUST be capable of processing values with or without time duration offsets and SHOULD implement comparisons as defined in the XML schema datatypes specification.

2.2 Naming Conventions

FpML uses two main naming conventions throughout its definitions (sometimes with an additional suffix). In this document these conventions are referred to as 'lowerCamelCase' and 'UpperCamelCase'.

2.2.1 lowerCamelCase

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

2.2.2 UpperCamelCase

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

2.2.3 Groups and Enumerations

  • Groups are named with the suffix '.model'.
  • Enumerations are named with the suffix 'Enum'.

2.2.4 Definitions and References

The following pattern distinguishes between Definitions and References:

  • xyz - for the definition of the concept (i.e. trade)
  • xyzId - for an identifier to the concept (i.e. tradeId)
  • xyzReference - for an internal href reference to the concept (i.e. tradeReference)

2.2.5 Naming Anomalies

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.

2.3 XML Schema Design Rules

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.

2.3.1 Qualification

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>
				

2.3.2 File Structure

In FpML each schema document when processed as the root schema must be valid XML Schema and have valid eCore reference attributes. This is not a rule enforced by the W3C XML Specification but it is required by FpML to avoid issues with tools.

2.3.2.1 Circular Dependency

A circular dependency arises when an included schema document includes a schema document that has been previously processed. A number of XML schema processing tools do not detect this situation and malfunction.

FpML schema documents MUST NOT include each other in a circular manner.

2.3.3 Attributes

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.

2.3.4 Attribute Groups

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>
				

2.3.5 Elements

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.

The names of elements SHOULD be carefully selected to indicate clearly the business meaning of the data value or data structure. As XML structures information hierarchically the name of a contained element SHOULD NOT be prefixed with all or part of its parent element's name.

2.3.5.1 nillable

Element definitions within an FpML compliant schema may be marked as nillable to allow their content to be omitted from an instance document without breaking XML validation rules.

The use of nillable is only allowed within the schema to allow a document creator to omit element content which they can not reasonably be expected to provide at all times (e.g. to allow summary product definitions in pricing reports, etc.). Types and elements used to construct messages where full product definitions are required (e.g. confirmation, matching, etc.) are SHOULD NOT allow nillable element content.

2.3.5.2 Substitution Groups

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 in conjunction with user extensions.


<product xsi:type="Swap">
  ... Swap content model here
</product>
					
2.3.5.3 Type Substitution

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).

2.3.6 Model Groups

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>
				
images/TypeA.jpg

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>
				
images/TypeB.jpg

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).

2.3.7 Simple Types

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 (e.g. an enumeration). 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).

2.3.8 Complex Types

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.

2.3.9 Content Models

XML schema allows the content model for a complex type to be defined in a number of ways. This section describes the preferred options within an FpML schema.

2.3.9.1 Sequential

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.

2.3.9.2 Choice Groups

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.

images/WrongChoice.jpg

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.

images/RightChoice.jpg
2.3.9.3 Ordering within Repetitions

Many of the elements that comprise of the FpML schema are allowed to repeat (i.e. their 'maxOccurs' attribute has a value greater than one or is 'unbound'). In almost all cases the order in which the repeating structures are generated within the document has no impact on the overall business interpretation of the data being described.

There are a small number of exceptions to this where the business data has no naturally occurring values that can be used to imply an ordering (e.g. repeating postal address lines) and the order of appearance must be treated as significant.

Processing applications MUST NOT assume that the order of data in a document is significant if it contains sufficient business values to allow an ordering to derived during processing. For example the sequence of 'legs' within a product, business center codes in a list, cashflows, Bermudian exercise dates, etc. SHOULD NOT be assumed to be any particular order (e.g. first to last, lexical, etc.).

2.3.9.4 Unordered Content

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.

2.3.9.5 Mixed Content

FpML DOES NOT allow the used of mixed content within elements. An FpML element MUST contain either a single data value (e.g. integer, date, enumerated value, etc.) or a series of sub-elements described by a selection of sequences and/or choice groups.

2.3.9.6 Validation

The way in which the content model for a complex type or model group is designed directly affects the amount of validation that can be performed during XML parsing and the amount that will have to be performed subsequently by program code. For example, it is often the case that the elements comprising the definition of a complex business object are related such that the presence of one implies the presence or absence of others.

A simple approach to modelling such business objects is to consider only the cardinality of each element. This leads to the creation of types containing a single sequence of mandatory and optional elements. Whilst such types will accept all valid element sequences they also accept invalid element combinations because the grammar does not express any inter-element relationships.

Using a combination of sequences and choices the XML grammar for a complex business object can be constrained to make it reject instances using invalid element combinations at the cost of a more complex content definition. Which such definitions may not be able to rule out every invalid case they significantly reduce the number of invalid combinations that must be checked through the use of programmed validation rules.

The AWG believes that in the interest of consistency of validation and interpretation between FpML processors the use of validating content definitions is preferred.

2.3.10 Boolean Values

A boolean value is one that can have only two possible states. The simplicity of these values means that there are several possible ways to model them in XML schema, each having its own set of pros and cons. Further complexity is often introduced by the requirement to have the value itself be optional, so that it can be excluded from product variants or a message structure where it is not required.

Using the features of schema and the conventions established for FpML there are four techniques that could be applied to the modelling of booleans, namely:

  • The presence or absence of an optional empty element.

    
    <isCashSettled/>
    						
  • An element defined using the XML schema defined boolean type and allowed to contain one of the values 'true', 'false', '1' or '0'.

    
    <isCashSettled>false</isCashSettled>
    						
  • An element defined using a simple type representing an enumeration of two possible values.

    
    <settlementMethod>Cash</settlementMethod>
    <settlementMethod>Physical</settlementMethod>
    						
  • An element defined using a scheme referencing type where the scheme itself supports only two valid code values.

    
    <settlementMethod settlementMethodScheme="http//...">Cash</settlementMethod>
    <settlementMethod settlementMethodScheme="http//...">Physical</settlementMethod>
    						

If the values 'true' and 'false' adequately express the semantics of the data value then the preferred FpML approach is the second, that is, boolean values MUST BE modelled using the XML schema type boolean. For example:


..
<principalExchanges>
  <initialExchange>true</initialExchange>
  <finalExchange>true</finalExchange>
  <intermediateExchange>false</intermediateExchange>
</principalExchanges>
...
				

This approach is consistent with the modelling of other value types and allows values to be absent if not required.

There are a few cases in the FpML schema where the existence of an empty element has been used in the model. These MAY BE deprecated and replaced in future releases of FpML.

In many cases the use of an enumeration may provide clearer business explanation of the two states than a simple 'true' or 'false'. This method SHOULD also be used if there is any possibility of there being more that two states at some point in the future. For example if we wanted to add 'Chattel' an acceptable form of settlement at a later time then using an enumeration would allow the new state to be introduced without breaking backwards compatibility.

Scheme based enumerations usually have a large domain of possible values which change frequently. Whilst technically possible, using a scheme reference to express a boolean value is not an effective solution.

2.3.11 Scheme Values

The XML schema type 'token' MUST be used as the datatype for elements containing scheme code values. In addition the 'maxLength' facet MUST be set so that the code is limited to 255 characters. This is a new constraint not imposed in FpML releases prior to 4.5 and is intended to assist with mapping XML to persistent storage, such as relational databases.

In practice code values SHOULD NEVER need to be as long as 255 characters and the AWG recommends that designers never create codes longer that 127 characters. FpML's own modelling working groups WILL NEVER define a code longer than 63 characters.

2.3.12 Annotation

Designers of FpML XML schemata MUST embed documentation within their schema components to enable the production of documentation automatically from the schema source. All global types and elements MUST have a definition. XML schema allows multiple annotations for each component differentiated by the 'xml:lang' attribute and designers MAY provide multi-lingual text. Documentation MUST always be included within an xsd:annotation. 'Floating' documentation (or comments) is not allowed in the FpML schemata.


<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).

2.3.13 Deprecated Structures

2.3.13.1 Definition

Any feature that appears in the resultant XML document or process instance may be deprecated - a node, code value, URI, correlation, etc.

A deprecated feature of FpML is one that should not be used. Deprecation is indicated to discourage usage. A feature is marked as deprecated temporarily to provide backwards compatibility.

A deprecated feature will almost always be removed in the next major version, though retention can be justified.

For full backwards compatibility, it is recommended to stay on the same version of the schema the implementer wishes to remain compatible with.

2.3.13.2 Flag

FpML defines a deprecated flag as an attribute to the FpML Schema to point at deprecated features that will be removed in the next major release. fpml-annotation:deprecated="true" is used to mark something as deprecated. In addition, a fpml-annotation:deprecatedReason attribute contains the rationale of the deprecation. These attributes are defined within a separate namespace called http://www.fpml.org/annotation.


<xsd:element name="contractualSupplement" type="ContractualSupplement" minOccurs="0"
 maxOccurs="unbounded" fpml-annotation:deprecated="true"
 fpml-annotation:deprecatedReason="The contractualTermsSupplement includes the publication date,
 which was not present in the contractualSupplement">
  <xsd:annotation>
    <xsd:documentation xml:lang="en">DEPRECATED - This element will be removed in the next major
	  version of FpML. The element contractualTermsSupplement should be used instead. Definition: A
	  contractual supplement (such as those published by ISDA) that will apply to the trade</xsd:documentation>
  </xsd:annotation>
</xsd:element>
					

2.4 Object Oriented Idioms

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).

2.4.1 Types

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.

images/Class.jpg

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.

2.4.1.1 Complex Content

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.

2.4.2 Inheritance

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.

2.4.2.1 By Extension

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.).

images/Extension.jpg

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.).

It's important to note that the use of extension in FpML is restricted to genuine cases of extension by inheritance, rather than a mechanism for grabbing a set of common properties.

2.4.2.2 By Restriction

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).

images/Restriction.jpg

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.

FpML no longer recommends the use of inheritance by restriction (for complex types) because of implementation issues and all instances of it where removed in release 4.2.

2.4.3 Abstract Types

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.

2.4.4 Arrays (Sequences)

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

images/MasterDetail.jpg

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.

images/Container.jpg

Such a model would result in documents with the following content:


<master>
  ...
  <details>
	<count>2</count>
	<detail>...</detail>
	<detail>...</detail>
  </details>
</master>
				

2.4.5 Association

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.

images/Association.jpg

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.

2.4.6 Aggregation

Like association, aggregation is a relationship between two objects. However, unlike association, the aggregated object does not have an independent existence.

images/Aggregation.jpg

2.4.7 Aggregation of Sub-Types

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.

images/AggregationSubtypes.jpg

3 References

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.

3.1 References to Objects

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:

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.

3.1.1 Intra-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.

A reference must point to a single target or to a common (possibly abstract) supertype of the possible targets in FpML. This principle is not enforced by XML Schema validation but it defines a design rule in order to have a clear implementation of intra-document references.

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).

3.1.1.1 Differences compared to Architecture 1.0

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 standards 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.

3.1.2 Inter-Document

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.

For example the element <publiclyAvailableInformation> structure used within a CreditEventNotification message contains a <url> element that may contain the HTTP address of some information describing the event, for example an online news article or press release.

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.

3.2 References to Values

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:

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.

3.3 Enumerations

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. In terms of naming conventions, enumerations end with the suffix 'Enum'.

Two naming conventions are used in conjunction with enumerated values in FpML, namely

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.

3.4 Schemes

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:

The URI for a scheme can be categorized as one of the following:

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.

3.4.1 Genericode

Since FpML 4.2 the standard scheme code lists documented within the specification have also been available as XML data files encoded using the Genericode representation. More information about Genericode can be found at the following location.

4 Namespaces & URIs

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.

4.1 The Rationale of the 1.0 FpML Architecture

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.

4.2 Changes Introduced by XML Schema

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.

4.3 Namespaces in FpML 4.0 and beyond

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.

4.4 URI Recommendations

URIs are used in a number of different situations, namely:

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.

4.4.1 URIs for FpML XML Schema

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.

4.4.2 URIs for FpML Schemes

The FpML 2.2 Architecture specification defines two formats for FpML controlled scheme URIs; a canonical form that does not include version information and a specific version URI.

  • Canonical form:

    http://www.fpml.org/AAAA/BBBB

  • Versioned form:

    http://www.fpml.org/AAAA/BBBB-CCC-DDDD-DD-DD

The components of these URIs are defined as follows:

  • The protocol and server identifier. FpML 1.0 and 2.* Architecture compliant documents use "http://www.fpml.org".

  • A marker string, "AAAA" in this example. This is "coding-scheme" for FpML issued specifications and "coding-scheme/external" for external schemes that are assigned and FpML URI because they do not have an externally defined URI of their own. Additional markers may be introduced in the future.

  • A string, "BBBB", indicating the name of the particular coding scheme. The field consists of lower case letters and numbers. Minus signs ('-') can also be used, except for the initial or final character.

  • The version, "CCC", indicates the version of the coding scheme. 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, "DDDD-DD-DD", 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 FpML controlled schemes.

For implementation reasons the default URI for the external schemes may not be changed until the publication of a major version.

4.4.2.1 Processing Scheme URIs

The introduction of standard canonical URI forms for all FpML controlled schemes means that applications must apply slightly different validation processing logic depending on the type of scheme used on a document.

  • When a canonical URI is used to reference a scheme code list the processing application SHOULD validate code values against the latest set of codes that it is aware of.

  • When a versioned URI is used the application MUST validate against the specific code list referenced and no other.

In practice it may be possible for applications to use the same processing logic to handle both conditions.

In releases of FpML between 4.0 and 4.4 inclusive the versioned scheme URI is used as the default value scheme URI attributes. From FpML 4.5 the default values will be based on the canonical form.

4.4.3 URI Examples

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/coding-scheme/external/iso4217

    is the FpML assigned URI for the external coding scheme defined by the ISO 4217 specification.

  • http://www.fpml.org/coding-scheme/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.

5 Versions

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:

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.

5.1 Version Identification

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>
			

5.2 Modular XML Schema Structure

The following standards apply to FpML Architecture 2.1 compliant schemata.

5.3 XML Schema Versioning

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 occurred 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 may 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.

5.4 Versioning of External Entities

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.

5.5 Backwards Compatibility

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 or optional attributes is backwards compatible. The approach minimises the impact on bespoke FpML extensions and business rules.

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.

The meaning of existing elements and attributes must not be affected by the additional elements and attributes. For example adding an optional element "quotationType" that changed whether an existing element was per cent or per mille, is not permitted.

5.6 Major and Minor Versions

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 then a description of the rationale for each of the minor levels should be given.

5.7 Object Identification

5.7.1 Principles

FpML defines a set of principles for business object identification for objects such as Trades:

  • In terms of definitions, an identifying token is a string meeting the xsd:token data type requirements that does not include any embedded version information.
  • A token used by an institution to identify a business object (such as a trade) must uniquely identify that object; in other words, it may be assigned to only one object.
  • A token used by an institution to identify a business object (such as a trade) must not change during the life of that object.
  • Version numbers must be positive and increasing, but do not need to be monotonic (i.e. there may be gaps between the numbers).
  • Version numbers may be updated only by the institution that created them and maintains them. In other words, one institution cannot update a version number originally assigned by another institution.
  • It must be clear to the recipient of a message what identification token(s) and version number(s) for each business object:
    • were assigned by the sender of the message.
    • are to be used for retrieving the current known state of the object.
    • are to be used for any reporting back to the originator.
  • If more than one identification token or version may be used for these purposes, an unambiguous rule for resolving identification conflicts must be defined.
  • Identification conflict mechanisms that rely on information not contained in the message (for example, ones relying on lists of scheme URIs maintained by the recipient) are undesirable compared to mechanisms that rely only on the message content.

Implementations of object identification in FpML should follow these principles.

6 Extending FpML

This section looks at how the FpML implementers can extend or modify the core FpML grammar to suit their own purposes.

6.1 Introduction

FpML follows an open standards development process based on producing a consensus 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:

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.

6.2 Adding new Product

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:

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>
			

6.3 Adding a new Message

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>
			

6.4 Extending Existing Content

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.

images/PartyTradeInformation.jpg

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>
			

6.5 Restricting Existing Content

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 constraint, namely:

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.

6.5.1 Restricting Content Globally

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/license/license.html
  -->
  <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>
				

6.5.2 Restricting Content Locally

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/license/license.html
  -->
  <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>
				

6.6 Restricting an Enumeration

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>
			

6.7 Restricting a Scheme

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>
			

7 FAQ

This section contains a set of frequently asked questions and answers directed at the Architecture Working Group.

7.1 Can I add new features directly to the FpML Schemas?

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.

7.2 Why can't I extend an enumeration?

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.

8 W3C XML Schema - A Summary

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.

8.1 Namespaces

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.

8.2 Scoping

Definitions within an XML schema may either be defined 'globally' at the outermost level of the schema or 'locally' within another definition.

XML schemas are commonly classified into one of three (bizarrely) named groups according to how they use global and local definitions, namely:

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.

8.2.1 Scoping and Namespaces

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.

8.3 Attributes

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.

8.3.1 Attribute Groups

A set of attributes that appear commonly together throughout a schema can be collected into a reusable attribute group definition and referenced as needed from other content definitions.

8.4 Elements

Elements provide the main structural comments 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 may 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"/>
			

8.4.1 Model Groups

A set of elements that appear commonly together throughout a schema with the same cardinalities can be collected into a reusable 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.).

8.4.2 Substitution Groups

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.

8.5 Types

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.

8.5.1 Derivation by Extension

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.

8.5.2 Derivation by Restriction

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 cardinality to make an optional element mandatory or reducing the maximum cardinality to remove an optional element altogether).

8.5.3 Type Substitution

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.

8.6 Integrity

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.

8.6.1 Uniqueness

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>

				

8.6.2 Keys & Key References

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.

Valid XHTML 1.1! Valid CSS!