FpML Architecture Specification 3.1 Second Working Draft 28 July 2017

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

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

Latest Recommendation: http://www.fpml.org/spec/fpml-arch-3-0-rec-1

 

Document built: Fri 2017/07/28 10:30:00

Copyright (c) 1999 - 2017 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/the_standard/fpml-public-license/




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 Previous Versions
             1.1.1 Changes Compared to Architecture 3.0
             1.1.2 Changes Compared to Architecture 2.2
             1.1.3 Changes Compared to Architecture 2.1
             1.1.4 Changes Compared to Architecture 2.0
             1.1.5 Changes Compared to Architecture 1.0
        1.2 A Word on Schema Design 'Best Practice'
        1.3 Future Work
             1.3.1 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 Suffixes
             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 Source of Coding Schemes
             3.4.2 Character Set
             3.4.3 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.3.1 Usage in FpML 5.0
        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.1.1 Version Identification in FpML 5
        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 Build Versions
        5.8 Object Identification
             5.8.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.5.3 Restricting an Enumeration
             6.5.4 Restricting a Scheme
        6.6 Extending Multiple Views
    7 Messaging Header
        7.1 Using the message header for validation
        7.2 Using the message header to validate business content
        7.3 Using the message header as business data
    8 FAQ
        8.1 Can I add new features directly to the FpML Schemas?
        8.2 Why can't I extend an enumeration?
    9 W3C XML Schema - A Summary
        9.1 Namespaces
        9.2 Scoping
             9.2.1 Scoping and Namespaces
        9.3 Attributes
             9.3.1 Attribute Groups
        9.4 Elements
             9.4.1 Model Groups
             9.4.2 Substitution Groups
        9.5 Types
             9.5.1 Derivation by Extension
             9.5.2 Derivation by Restriction
             9.5.3 Type Substitution
        9.6 Integrity
             9.6.1 Uniqueness
             9.6.2 Keys & Key References

1 Introduction

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

The FpML 3.1 Architecture builds upon the earlier FpML Architecture specifications and the conventions of FpML 1.02b before that. The 3.1 release updates the specification to include the new conventions adopted to support the FpML 5.0 grammar.

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 Previous Versions

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

1.1.1 Changes Compared to Architecture 3.0
  • General cleanup (e.g. typos, removed references to older 4.x versions where applicable)

    Clarified usage of actualBuild / expectedBuild. See "Build Versions" section.

    Restricted the use of Special Characters in coding schemes and annotations to printable ASCII character. See new "Character Set" section.

    Provide guidance on source of coding schemes. See "Scheme" section.

    Added new section on the role of the "Message Header".

1.1.2 Changes Compared to Architecture 2.2
  • The use of multiple namespaces.

    The FpML 5.0 grammar is distributed as multiple XML schemas, each specialised to suit a particular set of related business processes. This allows product, and other business object, representations to be adjusted to each usage (e.g. strict for confirmation, looser for reporting, etc.).

  • Namespaces shared by multiple releases

    From FpML 5.0 onwards the namespace used to identifiy a schema release MAY not be unique. A series of compatible releases WILL share a common namespace URI which is based on the major component of the version number (e.g. '5') and a 'service pack' indicator (e.g 'sp1') for all releases other than the first.

  • The removal of common FpML root element.

    Type substitution on the root element is no longer used to select the message type and its associated content model. The <FpML> element has been removed from the schema.

  • The FpML 'version' attribute has been renamed to 'fpmlVersion'.

    To make it easier to search for the start of FpML content within an encapsulating XML document the version attribute has been renamed to make it more distinctive. In addition instead of being a list of enumerated values (e.g. '5-0', '5-1') it is defined as a regular expression pattern that will match any version in the same major series (e.g. '5-(([1-9][0-9]+)|[0-9]')).

  • New fixed 'fpmlSchemaVersion' attribute added

    Provides the actual schema version number in the XML infoset created during parsing as this can no longer be derived from the namespace. Application code designed to support multiple versions of FpML can use this to determine the schema that the namespace was resolved to at runtime.

  • The use of the root element name to express message type.

    In FpML 5.0 every message has been given its own global element which can appear as a document root element. Business process related messages are typically only defined in one of the FpML process namespaces but some common messages used for error handling are defined in multiple namespaces (e.g. messageRejected).

1.1.3 Changes Compared to Architecture 2.1
  • Added a canonical form for all scheme URIs has been introduced along with processing semantics.

  • Added a physical maximum length constraint on scheme values and suggested length limits for FpML and user defined values.

  • Documentation annotations are restricted to English due to maintenance and tool issues with multi-lingual descriptions.

  • The use of special characters in annotations is limited to printable ASCII character. See the "Character Set" section.

1.1.4 Changes Compared to Architecture 2.0
  • The URI structure for coding schemes has been changed. See section 4.4.2 URIs for FpML Schemes.

  • Added guidelines for modeling boolean values. See section 2.3.9. Boolean Values.

  • Added validation section. See section 2.3.8.4. Validation.

  • Added additional comments on date and dateTime data types.

  • Added additional comments on the use of nillable elements.

  • Updated section on naming conventions.

  • Added rule not allowing circular includes.

  • Updated Annotation section, making definitions for all global types and elements required.

  • Added section on deprecated structures.

1.1.5 Changes Compared to Architecture 1.0
  • 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.

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

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

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

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

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

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

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

Throughout the development of FpML the Architecture Working Group has looked to other forums and standards groups for guidance and advice on the best way to use XML schema. The results of searches for information on best practice have largely been disappointing.

Much of the information on 'Best Practice' publicly available on Internet does not apply to the finance domain. Many of the available documents are based on draft releases of the specification rather than the final recommendation. Often the position argued is based on the assumption that the data represents the persistent state of some object oriented data structures (rather than a model of present day information sources with all its irregularities), or is based on a poor understanding of schema and the interplay between its features.

The schema standard itself is a compromise between two schools of thought, namely Object Oriented Design and Information Modelling. It frequently offers more than one solution to a design problem, each with its own set of trade offs for re-use and extensibility. As a consequence we have concentrated on determining how best to use the features of XML schema to model financial information for FpML, rather the best approach for all problems.

Readers wishing to research into best practice for themselves might like to start with the following links:

Following the publication of this document the AWG will continue its investigations into determining the best way to represent the FpML grammar and manage the complexity created by its expansion into new product areas and business processes as well as the more practical issues such as offering guidance on implementation.

1.3.1 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 than can currently be provided by XML schema and is currently being researched by the Validation working group.

This section defines the FpML style for structuring XML schema. It defines the rules as they apply to the various components of an XML schema and shows how the basic elements of object oriented design would be mapped to XML types and elements.

The rules in this section have been based on the following XML schema recommendations:

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

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 Suffixes

Suffixes are used in conjunction with UpperCamelCase identifiers to create standardised names for some XML Schema components. In particular:

  • Model group names have the suffix '.model'.

  • Attribute group names have the suffix '.atts'.

  • Enumerations are named with the suffix 'Enum'.

2.2.4 Definitions and References

The following naming pattern is used throughout the FpML schema to distinguish 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 grammar contains a few identifiers that do not conform with the architecture specification naming conventions. Many of these identifiers existed within previous release of the grammar and changing them may affect operational systems or their ability to reprocess already archived documents.

This issue of when and how to bring these names into line with the conventions is being discussed by the FpML coordination committee. When corrections to identifier names take place they will be documented as part of the release documentation.

This section defines the design rules that FpML imposes of each feature of the XML schema language to ensure consistency of usage during the modelling process.

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 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 those used as document root elements 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). Type substitition is one of the key techniques for extending the data content of existing types without editing the schema.

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 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. 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="en">The specific time of day at which the calculation agent values the underlying.
	</xsd:documentation>
  </xsd:annotation>
</xsd:element>
				

XML schema allows multiple annotations for each component differentiated by the 'xml:lang' attribute and this feature was used previously by FpML to support multi-lingual text for portions of the schema but it has proven difficult to maintain and caused problems with some tools. As a result the FpML architecture no longer supports the use of multi-lingual annotations and designers MUST only provide documentation in English.

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>
					

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

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:

  • Repeat the whole of the data object every time it is required.

  • Include the data object definition once and use references subsequently

Simple repetition can lead to large XML documents, if the data object is either frequently repeated or if it requires a large number of tags to define. A reference requires less XML code than object repetition and ensures consistency as there is only ever one instance definition.

XML 1.0 provides a several reference mechanisms based on the use of URLs and ID/IDREF attributes. Support for these mechanisms is continued in XML schema and enhanced with additional validation.

Within an XML schema the style of reference available is determined by the grammatical construction used to define it. The following section look are specific types of reference and show how they should appear in a conforming FpML document.

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 proved to be less 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.

Many of the data elements defined in the FpML grammar are restricted to holding a limited set of values. For example day count convention, option type, or currency code are all examples of data elements which have a finite set of 'legal' values. Such restricted sets of values are frequently referred to as domains, and an individual value with a set is a 'domain value'.

It is also important to note that some domains are more likely to be modified or extended than others and that the act of doing so may or may not affect the interpretation of the grammar and existing documents. The AWG suggests that domains can be further categorised as follows based on this behaviour:

  • Closed domains are those for which every possible value can be listed now and for which future change is extremely unlikely. Examples are days of the week or period modifier (e.g. day, week, month, etc.).

  • Controlled domains are those for which a change would affect the interpretation or processing of documents. Date roll conventions for example would be considered controlled as it is possible that new ones may be created in the future and the addition would require software change (e.g. for date calculation and pricing).

  • Open domains are those for which the set of active values is large and constantly modifying. Although changes do not affect the interpretation of documents. Examples are currency, business center and party codes.

In the FpML 1.0 Architecture specification the use of enumerations was not endorsed by the AWG because in XML 1.0 with a DTD specified grammar they could only be applied to attribute values, and FpML does not allow business data to appear in attributes. An XML schema based grammar can apply enumerations to element values allowing the additional validation provided by them to be applied to FpML.

As a result a large number of the closed and controlled domains previously provided as schemes have been replaced with enumerations within the schema. If it becomes necessary to extend these definitions to accommodate new financial products then FpML will release a new version with a release number determined by the compatibility of the changes with previous releases.

The migration of the FpML grammar to XML schema allows the use of schema based enumerations for 'closed' and 'controlled' domains. For consistency every such domain SHOULD be defined as a simple type which is a restriction on the standard XML schema data type token. In terms of naming conventions, enumerations end with the suffix 'Enum'.

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

  • Where an externally defined domain of values is being represented (e.g. BIC codes, SWIFT location codes, ISO currency codes, etc.) the naming convention of the source is used.

  • Where the domain has been created by the FpML schema designers the domain values SHOULD use UpperCamelCase.

For example the following XML fragment shows how the enumeration type for the compounding method domain is defined.

				
<xsd:simpleType name="CompoundingMethodEnum">
  <xsd:annotation>
	<xsd:documentation source="http://www.FpML.org" xml:lang="en">The compounding calculation method</xsd:documentation>
  </xsd:annotation>
  <xsd:restriction base="xsd:token">
	<xsd:enumeration value="Flat">
	  <xsd:annotation>
		<xsd:documentation source="http://www.FpML.org" xml:lang="en">Flat compounding. Compounding excludes the spread. Note that the first compounding period has it's interest calculated including any spread then subsequent periods compound this at a rate excluding the spread.</xsd:documentation>
	  </xsd:annotation>
	</xsd:enumeration>
	<xsd:enumeration value="None">
	  <xsd:annotation>
		<xsd:documentation source="http://www.FpML.org" xml:lang="en">No compounding is to be applied.</xsd:documentation>
	  </xsd:annotation>
	</xsd:enumeration>
	<xsd:enumeration value="Straight">
	  <xsd:annotation>
		<xsd:documentation source="http://www.FpML.org" xml:lang="en">Straight compounding. Compounding includes the spread.</xsd:documentation>
	  </xsd:annotation>
	</xsd:enumeration>
  </xsd:restriction>
</xsd:simpleType>
			

Domains which have been converted to enumerations in this manner no longer have any qualifying 'scheme' or 'schemeDefault' attributes.

Domains which are too large or too dynamic to be expressed as an enumeration remain supported as schemes (i.e. a combination of an identifying URI and a data value) although there are some modifications to their definition, namely:

  • A domain no longer has a schemeDefault attribute on the root FpML element.

  • Every scheme value reference MUST be qualified explicitly with a scheme URI on the referencing element.

  • The use of special characters in coding schemes is limited to printable ASCII character. See the "Character Set" section below.

  • If FpML defines a standard URI for a domain then its scheme attribute HAS a default value that MAY be overridden in the instance. A scheme provides alternate identifiers for one identity but it is not used to identify things other than the identity of the thing that contains it.

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

  • An external coding scheme, which has a well-known URI. In this case the URI is assigned by an external body, and may or may not have its own versioning and date syntax or semantics. The external body may be an open standards organization, or it may be a market participant.

    • For example: http://www.fpml.org/coding-scheme/external/exchange-id-MIC-1-0
  • An external coding scheme, which does not have a well-known URI. In this case FpML assigns a URI as a proxy to refer to the concept of the external scheme, but this URI will not be versioned or dated.

    • For example: http://www.fpml.org/coding-scheme/business-center-7-21
  • An FpML defined coding scheme but with values defined by external sources. In this case the scheme is still fully under FpML control and the URI will change reflecting newer versions and revisions as the scheme evolves and changes. The source of each value will indicate the external source where it is coming from.

    • The coding scheme name may contain the organization providing the source of the values. In this case the name of the organization will be added as prefix.
    • For example: http://www.fpml.org/coding-scheme/esma-product-classification

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 Source of Coding Schemes

Guidelines on specifying the source of coding schemes:

- The intent must be considered. If, for example, it is an ISDA code that we tweaked slightly to make it machine readable, it is still an ISDA code.

- If it is a code that was added by an FpML group because they felt they needed an extra code then the source should be FpML.

- The current system is flexible enough to allow mix sources. E.g., within a coding scheme file, the source is captured at the code level (and not at the coding scheme file level).

images/awg-coding-scheme-source1.png images/awg-coding-scheme-source2.png

3.4.2 Character Set

Coding scheme values and descriptions must use a standard character set. The set of characters allowed is the range of printable ASCII characters 32 to 126 (Hex 20 to 7E). All other special characters are excluded from coding schemes (whether codes or their descriptions).

images/ascii-table.png

Prior to FpML Coding Schemes version 1-71 (August 2015) a few coding schemes, within Commodities in particular, were using special characters. These have been streamlined to use the agreed character range defined above.

The restriction also applies to annotations. Non-standard characters creates issues for some implementations.

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

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, but it is hard to produce a DTD that uses namespaces and which will work in either type of parser.

Namespace awareness 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'.

There are examples of DTD based grammars where entities are used within the DTD grammar rules to expand into the prefix or an empty string to get around this problem but they would have made the already complex FpML grammar even more difficult to understand, so in the FpML 1.0 Architecture the decision was made to opt for a grammar without namespaces that would have the same definition and interpretation regardless of the capabilities of the parser.

XML Schema are inherently dependent on namespaces. To define a schema you must reference the schema grammar itself through is namespace (e.g. http://www.w3.org/2001/XMLSchema). Similarly an instance document refers its defining schemas and the schema instance definitions (e.g. http://www.w3.org/2001/XMLSchema-instance) through namespaces.

Unlike the W3C XML 1.0 recommendation for behaviour of namespaces in XML schema based documents is consistently defined for all parsers. Hence in our position with regard to namespaces in FpML documents was reversed in the FpML 2.0 Architecture Specification for XML Schema based documents.

Namespaces are a tool for avoiding name collisions so that 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 schema component. By adding the notion of a default namespace, the XML can also remain relatively non-verbose (e.g. elements from the most commonly used namespace can be used without any prefixes).

In the FpML 4.x series of releases each schema has been assigned its own unique namespace URI.

4.3.1 Usage in FpML 5.0

The FpML 5.0 specification adjusts the previous use of namespace URIs in two ways, namely:

  • From FpML 5.0 onwards a schema release that is entirely backwards compatible with the previous release will share the same namespace URI.

    Most FpML releases are completely backwards compatible, that is, they support all the products and messages defined in the previous release. Typically the only changes are new features to existing products, new products or new messages. Incompatible (or 'breaking changes') to established products are rarely made.

    To support this change in namespace usage the URIs themselves must be created using a different pattern. From FpML 5.0 they will be formed from the major version number (e.g. '5') followed by a 'service pack' indicator (e.g. 'sp1') for all subsequent incompatibe releases. For example:

    • http://www.fpml.org/2009/FpML-5/confirmation
    • http://www.fpml.org/2010/FpML-5-sp1/confirmation
    • http://www.fpml.org/2011/FpML-5-sp2/confirmation
    • http://www.fpml.org/2012/FpML-6/confirmation

    In the FpML 4.x series of schemas each release was given its own unique namespace URI derived from the version number. Documents referencing a particular namespace URI could only be parsed against the matching schema, and no other, without modification. Under the new namespace regime a document may be parsed against any 'compatible' schema associated with the referenced namespace URI.

    A technical note describing the rationale behind the namespace changes has been published by the AWG and is downloadable from http://www.fpml.org/documents/technote/xxx.doc.

  • Namespaces are used to implement 'views' that adjust product definitions to suit particular business processes or stage of the trade life cycle. The idea of 'views' has existed since the inception of FpML but all the initial design and development focussed on just the product 'confirmation' view.

    Starting with FpML 5.0 each release of the specification will be released as a set of schemas, one for each view. Each view will have its own unique namespace URI. There are no common sub-schemas shared by multiple views (e.g. chameleon schemas).

    To maintain consistency between the schemas they are generated automatically from a master schema that contains special annotations used to determine which components should be present in each target view namespace. These annotations allow components to be modified (e.g. type and cardinality can be adjusted to suit the target view) or excluded altogether if necessary.

    A separate technical note describing the master schema annotations and generation process has been published by FpML at http://www.fpml.org/documents/technote/FpMLViewGenerationSyntax20080207.doc.

The introduction of shared namespace URIs provides greater flexibility when inter-connecting systems using FpML based messages. With the old approach the systems at both ends of the connection would have to be updated if the FpML version used by either is changed. The new approach allows the systems to operate with different FpML versions provided they are compatible. Both systems only need to be updated if an upgrade to an incompatible release is required.

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

  • To identify standard XML Schema related definitions.

  • To identify the FpML content model (and in the future possibly sub-components of the content model).

  • To reference schemes defined outside of the FpML grammar.

Where FpML uses a component outside of its control (e.g. XML Schema itself, digital signatures, etc.) the URI defined for that component by its controlling organisation is used as is. For other FpML controlled components the URIs are defined according to the rules defined in the following sections.

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 major portion of the version number, a service pack indicator (for all updates) and the view name as show below.

  • http://www.fpml.org/FpML-MAJORVERSION[-SERVICEPACK]/VIEW

Given this definition the URI that will be used to reference FpML 5.0 confirmation view schema will be as follows:

  • http://www.fpml.org/FpML-5/confirmation

And the first service pack release will be as follows:

  • http://www.fpml.org/FpML-5-sp1/confirmation

4.4.2 URIs for FpML Schemes

The FpML 3.0 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-3-0

    represents the FpML 3.0 Architecture specification.

  • http://www.fpml.org/spec/2007/FpML-arch-3-0-2007-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/FpML-5/confirmation

    represents the first release of the FpML 5 grammar for confirmation.

  • http://www.fpml.org/FpML-5-sp2/confirmation

    represents the second service pack of the FpML 5 grammar for confirmation.

As was noted in the first version of the FpML Architecture specification, FpML is a living standard, evolving with time for a number of reasons, including:

  • Support for new types of financial product.

  • New roles for the FpML standard.

  • Advances in XML, in particular schemas.

Evidence of these changes can be seen in the series of FpML 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.w3.org/2001/XMLSchema-instance"
 xmlns="http://www.fpml.org/2003/FpML-4-0"
 version="4-0"
 xsi:type="MessageType">
  ...
</FpML>
			

5.1.1 Version Identification in FpML 5

The removal of the standard <FpML> root node from the 5.0 grammar and the additional of new message centric root elements has caused us to rethink the naming of the version attribute.

Many implementations embedded the FpML instance data with a large encapsulating XML instance. Previously it was possible to locate the start of the FpML section by searching for the FpML root element but now that there are many possible root elements and each release may add more we have decided to make the version attribute more distinctive so it can be used as a search target. To this end in FpML 5.0 the version attribute is now called 'fpmlVersion' and is present on all valid FpML document root elements.

The following XML fragment shows the document root element for an arbitary message type:

					
<someMessage
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns="http://www.fpml.org/FpML-5/confirmation"
 fpmlVersion="5-1">
  ...
</someMessage>
				

The namespace changes introduced in FpML 5.0 mean that there is no longer a direct correspondance between the namespace URI and the schema version. In order to provide a processing application with a way of determining which schema a namespace has been resolved to during parsing a new defaulted attribute 'fpmlSchemaVersion' will be added to the schema. The XML infoset created by a validating parse will contain a new fixed attribute on the root element containing the actual schema version number. For example, parsing the previous XML example against the schema for FpML 5.2 would produce an XML infoset providing both the intended and actual versions as if the original XML had resembled the following.

					
<someMessage
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.fpml.org/FpML-5/confirmation"
fpmlVersion="5-1" fpmlSchemaVersion="5-2">
  ...
</someMessage>
				

Many applications are built to process documents against a specific version of FpML and can safely ignore the new attribute, but those that accept multiple versions of FpML can use the version number to discover how their XML parser has been configured, for example when the mapping from namespace to schema file has been performed via an XML catalog file.

The following standards apply to FpML Architecture 3.0 compliant schemata.

  • An FpML namespace MAY be implemented as small number of modular component XML Schemas.

  • The main XML Schema for the FpML namespace SHOULD include (directly or indirectly) all the component schemas that comprise the namespace.

  • Even though the W3C XML Schema 1.0 specification explicitly allows circular includes between component schemas (a.xsd includes b.xsd, b.xsd includes a.xsd), FpML forbids them. The rationale for this constrain is the lack of tool support for XML schemas containing circular includes.

  • Each component XML Schema has an associated version number (e.g. in its filename). In any release of FpML the main XML Schema MUST change and some of the component XML Schemas MAY also change. Where a component XML Schema does not change, its version may be left unchanged.

The overall FpML standard follows a single release cycle specified by a single version string. Individual parts of the FpML XML Schema cannot change between releases of FpML as a whole.

The granularity of FpML versioning is based on the modularity of the FpML XML Schema. Every release of the FpML standard will involve assigning a new version to the FpML XML Schema and any component Schemas that have changed. FpML documents must use the new public URI created by this process to access the new features of the grammar.

Each FpML grammar is defined to accept only a specific set of version numbers. To date the changes between each version have been such that each release has been incompatible with the last and only major version changes have 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. 5-0 or 5-1) and validation rules may be defined to prevent the use of a new feature with an old version number.

External standards have their own versioning methodology. For example, FpML uses ISO currency code. In this standard currency codes may be added or removed from day to day without any change to the version number. FpML does not lock the standard. In turn, new ISO currency codes can be used without requiring a new release of FpML.

Where possible, every attempt should be made to keep changes to the FpML schema as backwards compatible as possible. In general, the loosening of restriction, or the adding of new optional elements 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.

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.

In FpML a pair of 'build' attributes were added to the schemas to allow the intermediate working draft releases of the FpML schemas to be differentiated from each other and primarily intended for use by institutions who choose to implement in parallel to the working groups rather than wait for public releases.

The build attributes only appear on document root elements and allow the sender and receiver to check that they are using the same version of the schemas.

  • The 'expectedBuild' attribute SHOULD be populated by the document creator and MUST contain the build number present in their copy of the FpML schemas.
  • The 'actualBuild' attribute MUST NOT appear in an instance document. It has default value defined within the FpML schema and is added to parsed XML output during processing.

By comparing the values of the 'expectedBuild' and 'actualBuild' attributes the document receiver can work out which release of an FpML schema version the creator is using.

- If 'expectedBuild' is the same as 'actualBuild' then both the creator and receiver are using the same release.

- If 'expectedBuild' is less than 'actualBuild' then the document was parsed against a newer release than the document creator expected but contains compatible content.

- If 'expectedBuild' is greater than 'actualBuild' then the document was parsed against an older release than the document creator expected but contains compatible content.

As FpML is normally 'backwards compatible' all old documents SHOULD be accepted by a new schema. If a document containing references to new features is validated against an older release of FpML that does not define the required elements, attributes or types then the XML parser will fail because of the presence of the incompatible content.

Examples:

  • If 'expectedBuild' is the same as 'actualBuild' then both the creator and receiver are using the same release.
  • Schema snippet:
			
			<xsd:attributeGroup name="VersionAttributes.atts">
				...
				
				<xsd:attribute name="expectedBuild" type="xsd:positiveInteger"/>
				<xsd:attribute name="actualBuild" type="xsd:positiveInteger" fixed="4"/>
				
			</xsd:attributeGroup>
			
  • Instance snippet:
			
			<executionNotification expectedBuild="4" ... />
			
  • If 'expectedBuild' is less than 'actualBuild' then the document was parsed against a newer release than the document creator expected but contains compatible content.
  • Schema snippet:
			
			<xsd:attributeGroup name="VersionAttributes.atts">
				...
				
				<xsd:attribute name="expectedBuild" type="xsd:positiveInteger"/>
				<xsd:attribute name="actualBuild" type="xsd:positiveInteger" fixed="4"/>
				
			</xsd:attributeGroup>
			
  • Instance snippet:
			
			<executionNotification expectedBuild="3" ... />
			
  • If 'expectedBuild' is greater than 'actualBuild' then the document was parsed against an older release than the document creator expected but contains compatible content.
  • Schema snippet:
			
			<xsd:attributeGroup name="VersionAttributes.atts">
				...
				
				<xsd:attribute name="expectedBuild" type="xsd:positiveInteger"/>
				<xsd:attribute name="actualBuild" type="xsd:positiveInteger" fixed="4"/>
				
			</xsd:attributeGroup>
			
  • Instance snippet:
			
			<executionNotification expectedBuild="5" ... />
			

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

This section looks at how 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:

  • Where the existing FpML grammar is being constrained (to eliminate parts of the grammar or reduce domain value choices) schema redefinition will be used. To implement such redefinitions a new schema module is required that will import and redefine components of the core schema but leave them in the same namespace.

    Instance documents are not affected by the creation of such a module, all that is required is a suitable mapping in the XML parsers entity resolver to map the system identifier to the filename of the redefining schema module.

  • Where the existing FpML grammar is being expanded we will add the new definitions to a new namespace and use either substitution groups or type substitution to introduce new definitions into instance documents.

    To make use of such an extension the instance document will have to include a declaration for the new namespace and such a document would fail validation if processed by an application that is unaware of the extensions.

A third technique involving the use of the FpML master schema generation tools will not be discussed but may be a better option for institutions that maintain a large and complex set of extensions that will be used in more than one view. A separate technical paper describing this approach will be published by ISDA.

The XML definitions to implement the extensions in this section are included in two example schemas distributed with this specification. The file 'fpml-acme-4-0.xsd' contains the redefined components whilst 'acme-1-0.xsd' contains extensions. The example instance documents use the 'schemaLocation' attribute to identify these files for the benefit of standard XML Schema and instance document editors in the absence of a properly configured entity resolver.

This section shows how a new product can be added to the FpML grammar in a new institution specific namespace. To create a new product two key definitions are required, namely:

  • A new complex type is need to define the content model for the new product. This type MUST be derived from the base FpML type 'Product' either directly or indirectly via another FpML product type (e.g. Swap, FxLeg, etc.). The content model may be defined by referencing existing FpML component type or by defining new components (in the new namespace).

  • A new global element MUST be defined which takes its content model from the new product type and which can substitute for the FpML global element 'product'.

The following schema shows the two definitions necessary to create a basic product type, in this case an 'AcmeOption', although no specific content model has been added to keep the example brief.

				
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns="http://www.handcoded.com/2007/FpML-Extension"
 xmlns:xs="http://www.w3.org/2001/XMLSchema"
 xmlns:fpml="http://www.fpml.org/FpML-5/confirmation"
 targetNamespace="http://www.handcoded.com/2007/FpML-Extension"
 elementFormDefault="qualified"
 attributeFormDefault="unqualified">
  <xs:import namespace="http://www.fpml.org/FpML-5/confirmation"
   schemaLocation="fpml-main-5-0.xsd"/>
  <!--New Product Type-->
  <xs:complexType name="AcmeOption">
    <xs:complexContent>
      <xs:extension base="fpml:Product">
        <xs:sequence>
          <xs:element name="someData" type="xs:normalizedString"/>
        </xs:sequence>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
  <!--New Product Element-->
  <xs: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.

				
<?xml version="1.0" encoding="UTF-8"?>
<requestTradeConfirmation fpmlVersion="5-0"
 xmlns="http://www.fpml.org/FpML-5/confirmation"
 xmlns:ext="http://www.handcoded.com/2007/FpML-Extension"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.fpml.org/FpML-5/confirmation fpml-main-5-0.xsd http://www.handcoded.com/2007/FpML-Extension ExtensionSchema.xsd">
  <header>
    <messageId messageIdScheme="http://www.handcoded.com/messageId">M293567/A</messageId>
    <sentBy>HANDCODED</sentBy>
    <sendTo>GLOBALEMARKETS</sendTo>
    <creationTimestamp>2007-12-14T14:05:07.23Z</creationTimestamp>
  </header>
  <trade>
    <tradeHeader>
      <partyTradeIdentifier>
        <partyReference href="HDCD"/>
        <tradeId tradeIdScheme="http://www.handcoded.com/trade-id">TD151207A</tradeId>
      </partyTradeIdentifier>
      <tradeDate>2007-12-14</tradeDate>
    </tradeHeader>
    <ext:acmeOption>
      <ext:someData>Real product definition data would go here</ext:someData>
    </ext:acmeOption>
  </trade>
  <party id="HDCD">
    <partyId>HANDCODED</partyId>
  </party>
  <party id="GEM">
    <partyId>GLOBALEMARKETS</partyId>
  </party>
</requestTradeConfirmation>
			

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.

				
  <!--New Message Type-->
  <xs:complexType name="AcmeMessage">
    <xs:complexContent>
      <xs:extension base="fpml:RequestMessage">
        <xs:sequence>
          <xs:element name="someData" type="xs:normalizedString"/>
        </xs:sequence>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
  <!--New Message Element-->
  <xs:element name="acmeMessage" type="AcmeMessage"/>
			

If the message is completely new then the designer SHOULD also create a new root element to allow it to be accessed in an instance document and when used to create a document instance the resulting XML would resemble this:

				
<?xml version="1.0" encoding="UTF-8"?>
<ext:acmeMessage fpmlVersion="5-0"
 xmlns="http://www.fpml.org/FpML-5/confirmation"
 xmlns:ext="http://www.handcoded.com/2007/FpML-Extension"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.fpml.org/FpML-5/confirmation fpml-main-5-0.xsd http://www.handcoded.com/2007/FpML-Extension ExtensionSchema.xsd">
  <header>
    <messageId messageIdScheme="http://www.handcoded.com/messageId">M293578/A</messageId>
    <sentBy>HANDCODED</sentBy>
    <sendTo>GLOBALEMARKETS</sendTo>
    <creationTimestamp>2007-12-14T14:56:08.19Z</creationTimestamp>
  </header>
  <ext:someData>Real message data would go here</ext:someData>
</ext:acmeMessage>
			

If the new message is an extension of an existing FpML message then the extending schema may define a new root element using the extended type or use type substitution on the original FpML root element. For example assuming the Acme schema defines an extension to the FpML 'RequestTradeConfirmation' message type then the following XML would be used to access it in an instance document.

For example if the extension schema contained the following definition...

				
  <!--An Extended Message Type-->
  <xs:complexType name="RequestTradeConfirmation">
    <xs:complexContent>
      <xs:extension base="fpml:RequestTradeConfirmation">
        <xs:sequence>
          <xs:element name="someData" type="xs:normalizedString"/>
        </xs:sequence>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
			

... then it could be used to create an instance document such as this.

				
<?xml version="1.0" encoding="UTF-8"?>
<requestTradeConfirmation fpmlVersion="5-0"
 xsi:type="ext:RequestTradeConfirmation"
 xmlns="http://www.fpml.org/FpML-5/confirmation"
 xmlns:ext="http://www.handcoded.com/2007/FpML-Extension"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.fpml.org/FpML-5/confirmation fpml-main-5-0.xsd http://www.handcoded.com/2007/FpML-Extension ExtensionSchema.xsd">
  <header>
    <messageId messageIdScheme="http://www.handcoded.com/messageId">M293567/A</messageId>
    <sentBy>HANDCODED</sentBy>
    <sendTo>GLOBALEMARKETS</sendTo>
    <creationTimestamp>2007-12-14T14:05:07.23Z</creationTimestamp>
  </header>
  <trade>
    <tradeHeader>
      <partyTradeIdentifier>
        <partyReference href="HDCD"/>
        <tradeId tradeIdScheme="http://www.handcoded.com/trade-id">TD151207A</tradeId>
      </partyTradeIdentifier>
      <tradeDate>2007-12-14</tradeDate>
    </tradeHeader>
    <ext:acmeOption>
      <ext:someData>Real product definition data would go here</ext:someData>
    </ext:acmeOption>
  </trade>
  <party id="HDCD">
    <partyId>HANDCODED</partyId>
  </party>
  <party id="GEM">
    <partyId>GLOBALEMARKETS</partyId>
  </party>
  <ext:someData>Additional message data would go here</ext:someData>
</requestTradeConfirmation>
			

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.

				
  <!--Extended PartyTradeInformation-->
  <xs:complexType name="PartyTradeInformation">
    <xs:complexContent>
      <xs:extension base="fpml:PartyTradeInformation">
        <xs:sequence>
          <xs:element name="tradingSystem" type="xs:normalizedString" minOccurs="0"/>
          <xs:element name="salesPerson" type="xs:normalizedString" minOccurs="0"/>
          <xs:element name="tradeAccount" type="xs:normalizedString" minOccurs="0"/>
        </xs:sequence>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
			

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.

				
<?xml version="1.0" encoding="UTF-8"?>
<requestTradeConfirmation fpmlVersion="5-0"
 xmlns="http://www.fpml.org/FpML-5/confirmation"
 xmlns:ext="http://www.handcoded.com/2007/FpML-Extension"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.fpml.org/FpML-5/confirmation fpml-main-5-0.xsd http://www.handcoded.com/2007/FpML-Extension ExtensionSchema.xsd">
  <header>
    <messageId messageIdScheme="http://www.handcoded.com/messageId">M293567/A</messageId>
    <sentBy>HANDCODED</sentBy>
    <sendTo>GLOBALEMARKETS</sendTo>
    <creationTimestamp>2007-12-14T14:05:07.23Z</creationTimestamp>
  </header>
  <trade>
    <tradeHeader>
      <partyTradeIdentifier>
        <partyReference href="HDCD"/>
        <tradeId tradeIdScheme="http://www.handcoded.com/trade-id">TD151207A</tradeId>
      </partyTradeIdentifier>
      <partyTradeInformation xsi:type="ext:PartyTradeInformation">
        <partyReference href="HDCD"></partyReference>
        <trader>Andrew Jacobs</trader>
        <ext:tradeAccount>Prop Trading</ext:tradeAccount>
      </partyTradeInformation>
      <tradeDate>2007-12-14</tradeDate>
    </tradeHeader>
    <ext:acmeOption>
      <ext:someData>Real product definition data would go here</ext:someData>
    </ext:acmeOption>
  </trade>
  <party id="HDCD">
    <partyId>HANDCODED</partyId>
  </party>
  <party id="GEM">
    <partyId>GLOBALEMARKETS</partyId>
  </party>
</requestTradeConfirmation>
			

Some implementers 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:

  • If the intention is to exclude the use of some elements under very specific conditions (e.g. content allowed in one variety of interest rate swap but not in another) then a custom validation rule is the easiest way to implement its detection.

  • If the intention is to exclude the use of some elements from all locations in the model where its defining type is used then a schema redefinition is the simplest approach.

  • If the intention is to exclude the use of some elements in some areas of the model but not others then creating a new restricted type and using type substitution may be easiest.

The definition of validation rules is the remit of the FpML Validation Working Group (VWG) and is described in their specification. The other approaches can be handled through XML Schema redefinitions.

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. Such restrictions MUST be performed in the same namespace as the original definition so typically a new schema must be created to which will be used to intercept the parsers access the FpML entry schema and modify the types as needed.

images/SchemaRedefinition.jpg

This technique is used in the following sections to illustrate the kinds of redefinition that are possible.

6.5.1 Restricting Content Globally

The Swapswire service disallows the presence of the elements 'cancelableProvision' and 'extendibleProvision' within its definition of a FpML swap. The removal of these elements can be performed from the XML schema for FpML by directing the XML parser to a schema containing the following definitions.

					
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
 xmlns="http://www.fpml.org/FpML-5/confirmation"
 targetNamespace="http://www.fpml.org/FpML-5/confirmation"
 elementFormDefault="qualified"
 attributeFormDefault="unqualified">
  <xs:redefine schemaLocation="fpml-main-5-0.xsd">
    <xs:complexType name="Swap">
      <xs:complexContent>
        <xs:restriction base="Swap">
          <xs:sequence>
            <xs:sequence>
              <xs:group ref="Product.model"/>
            </xs:sequence>
            <xs:sequence>
              <xs:element name="swapStream" type="InterestRateStream" maxOccurs="unbounded">
                <xs:annotation>
                  <xs:documentation xml:lang="en">The swap streams.</xs:documentation>
                </xs:annotation>
              </xs:element>
              <xs:element name="additionalPayment" type="Payment" minOccurs="0" maxOccurs="unbounded">
                <xs:annotation>
                  <xs:documentation xml:lang="en">Additional payments between the principal parties.</xs:documentation>
                </xs:annotation>
              </xs:element>
              <xs:element name="additionalTerms" type="SwapAdditionalTerms" minOccurs="0">
                <xs:annotation>
                  <xs:documentation xml:lang="en">Contains any additional terms to the swap contract.</xs:documentation>
                </xs:annotation>
              </xs:element>
            </xs:sequence>
          </xs:sequence>
        </xs:restriction>
      </xs:complexContent>
    </xs:complexType>
  </xs:redefine>
</xs:schema>
				

Applications which use XML catalogs to loosely define the mapping between schema namespace URIs and thier physical filing system location can easily be redirected to such a restricting schema instead of the original FpML definitions.

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.

					
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
 xmlns="http://www.fpml.org/FpML-5/confirmation"
 targetNamespace="http://www.fpml.org/FpML-5/confirmation"
 elementFormDefault="qualified"
 attributeFormDefault="unqualified">
  <!-- Either include or redefine the original FpML schema -->
  <xs:redefine schemaLocation="fpml-main-5-0.xsd">
    <!-- Redefined content -->
  </xs:redefine>
  <!-- Define a new restricted type in the FpML namespace -->
  <xs:complexType name="MySwap">
    <xs:complexContent>
      <xs:restriction base="Swap">
        <xs:sequence>
          <xs:sequence>
            <xs:group ref="Product.model"/>
          </xs:sequence>
          <xs:sequence>
            <xs:element name="swapStream" type="InterestRateStream" maxOccurs="unbounded">
              <xs:annotation>
                <xs:documentation xml:lang="en">The swap streams.</xs:documentation>
              </xs:annotation>
            </xs:element>
            <xs:element name="additionalPayment" type="Payment" minOccurs="0" maxOccurs="unbounded">
              <xs:annotation>
                <xs:documentation xml:lang="en">Additional payments between the principal parties.</xs:documentation>
              </xs:annotation>
            </xs:element>
            <xs:element name="additionalTerms" type="SwapAdditionalTerms" minOccurs="0">
              <xs:annotation>
                <xs:documentation xml:lang="en">Contains any additional terms to the swap contract.</xs:documentation>
              </xs:annotation>
            </xs:element>
          </xs:sequence>
        </xs:sequence>
      </xs:restriction>
    </xs:complexContent>
  </xs:complexType>
</xs:schema>
				

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

					
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
 xmlns="http://www.fpml.org/FpML-5/confirmation"
 targetNamespace="http://www.fpml.org/FpML-5/confirmation"
 elementFormDefault="qualified"
 attributeFormDefault="unqualified">
  <xs:redefine schemaLocation="fpml-main-5-0.xsd">
    <!-- Restrict the choice of values in an enumeration -->
    <xs:simpleType name="BusinessDayConventionEnum">
      <xs:restriction base="BusinessDayConventionEnum">
        <xs:enumeration value="FOLLOWING">
          <xs:annotation>
            <xs: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</xs:documentation>
          </xs:annotation>
        </xs:enumeration>
        <xs:enumeration value="MODFOLLOWING">
          <xs:annotation>
            <xs: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.</xs:documentation>
          </xs:annotation>
       	<xs:enumeration value="PRECEDING">
          <xs:annotation>
            <xs: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.</xs:documentation>
          </xs:annotation>
        </xs:enumeration>
        <xs:enumeration value="MODPRECEDING">
          <xs:annotation>
            <xs:documentation source="http://www.FpML.org" xml:lang="en">The non-business date will be adjusted to the first preceding day that is a business day unless that day falls in the previous calendar month, in which case that date will be the first following day that us a business day.</xs:documentation>
          </xs:annotation>
        </xs:enumeration>
      </xs:restriction>
    </xs:simpleType>
  </xs:redefine>
</xs:schema>
				

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

					
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
 xmlns="http://www.fpml.org/FpML-5/confirmation"
 targetNamespace="http://www.fpml.org/FpML-5/confirmation"
 elementFormDefault="qualified"
 attributeFormDefault="unqualified">
  <xs:redefine schemaLocation="fpml-main-5-0.xsd">
    <xs:complexType name="Currency">
      <xs:simpleContent>
        <xs:restriction base="Currency">
          <xs:enumeration value="EUR"/>
          <xs:enumeration value="GBP"/>
          <xs:enumeration value="USD"/>
          <xs:attribute name="currencyScheme" type="xs:anyURI" default="http://www.fpml.org/ext/iso4217-2001-08-15"/>
        </xs:restriction>
      </xs:simpleContent>
    </xs:complexType>
  </xs:redefine>
</xs:schema>
				

The techniques presented in the earlier sections can extend a single schema, but what if you need to make the same or similar changes to more than one FpML view schema, for example to make a product available in both the confirmation and reporting views?

If the extensions will be the same in all the views and are not constructed using FpML schema components then it would be possible to place them in a 'chameleon schema' (i.e. a schema having no namespace itself but whose components take on the target namespace of the schema they are included into) referenced from another view extending schema. This approach will work for simple utility types but is not a viable solution for more complex business object related definitions for which derivation from an FpML type or the use of FpML types to define it's content is inevitable (e.g. products, messages, etc.).

The message header contains technical information to be used as part of the processing and routing of a message. It provides a transport-independent way of tracking information about the transport. It can also be used without reference to the transport.

The below schema diagram shows the content model of the header found in all FpML message types (i.e. requests, responses, notifications and exception messages). The header is used to capture information such as who sent the message, who it was sent to, when the message was created, or the message identifier, for example.

images/message-header.png

7.1 Using the message header for validation

The information in the message header should be validated against the actual message transport by the receiver. It should also be used to validate the content of a message.

It is a two-step process meant to generate successive levels of trust in the message by ensuring consistency:

  • 1. Make sure what is in the message header is consistent with the transport (i.e. how the message was delivered). The sentBy field should be validated against the message queue.

  • 2. Once the message header can be trusted, it can be used to drive other validation downstream (e.g. is it a legal submitter? are the parties referenced inside the trade valid?)

As best practice,

  • 1. An implementation should validate the content of the message header against transport.

  • 2. Firms should use the data content in the message header as a source for validation for the content of the payload.

One advantage of the message header is that it is in XML format. It can easily be accessed through Xpath / XSLT. Conversely, information in the enclosing message transport envelope is harder to access and transport-specific.

The message header should be used to validate business content in the payload. For example,

  • Ensuring the sender of the message is the legal submitter of the trade – If there is a TradeSource party role in the payload, it should be validated against the sentBy field in the header. They have to be consistent. This check should prevent the forging of a message and provide some level of proof regarding who submitted the trade.

    Note: The receiver of the message may not necessarily be able to validate purely on the content of the message; validation may require additional reference data.

  • creation timestamp – service providers should develop rules to ensure the timestamp is not in the future. Nowadays messages arrive almost instantly. A message arriving earlier or hours later should be flagged. Service providers will have to decide what is relevant for them. Some services are time critical while other aren’t.

FpML does not prohibit the use of the message header as business data. We advise that if a firm uses information in the message header, it will probably need to be mapped. What is in the message header will probably be service-specific or linked to the transport and may not follow any data format or standard that would be appropriate for a regulator for reporting. The data inside the message header likely can’t be used without further mapping. A firm willing to do the mapping could use the information for business content.

				
<xsd:simpleType name = "BooleanLogic">
  <xsd:restriction base = "token">
    <xsd:enumeration value = "false"/>
    <xsd:enumeration value = "true"/>
  </xsd:restriction>
</xsd:simpleType>
			

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

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

In XML Schema an enumeration is defined using a simple type declaration with a set of value restrictions, as shown in the following example.

				
<xsd:simpleType name = "BooleanLogic">
  <xsd:restriction base = "token">
    <xsd:enumeration value = "false"/>
    <xsd:enumeration value = "true"/>
  </xsd:restriction>
</xsd:simpleType>
			

Simple types may be derived from each other but only via restriction, which means that it possible to allow only a subset of the original enumerated values to be accepted, but it is impossible to add new choices.

One way to circumvent this problem is to define a new type which is the union of some base enumeration and a new anonymous type containing the additional values. The following definition shows how this can be applied to the previous example to create a type that accepts 'true', 'false' or 'maybe'.

				
<xsd:simpleType name = "FuzzyLogic">
  <xsd:union memberTypes = "BooleanLogic">
    <xsd:simpleType>
      <xsd:restriction base = "token">
        <xsd:enumeration value = "maybe"/>
      </xsd:restriction>
    </xsd:simpleType>
  </xsd:union>
</xsd:simpleType>
			

It is important to note that this new type is not 'type compatible' with the original enumeration (as it is not directly a restriction of it) and cannot be used to override the type of an existing enumerated element but it can be used to define new elements.

This section is a brief summary of the features of XML schema and describes some of the implications of their use. It is not intended to be a full tutorial on the subject but serves to highlight the rational behind some of the architectural choices.

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

  • Have no namespace at all.

    A schema (and its constituent sub-schemata) may be defined without associating it to any namespace at all. Such a schema may be included into another schema in which case it takes on the namespace (if any) of the extending schema . The core schema designer must ensure that all element and type identifiers are unique within his schema.

    As the core schema has no namespace to qualify the element and type identifiers the designers of any extending schema must also avoid naming clashes by design. If the core schema is modified then it may inadvertently create a name clash with a definition in the extending schema making the taking up of new version problematic.

    Without a namespace it is not possible for instance documents to reference the schema, they can only be used as components to construct other XML Schemas.

  • Have one namespace.

    The schema (and its constituent sub-schemata) can be defined as belonging to a single target namespace. Again the core schema designer must ensure by design that there are no name clashes within the schema. An extending schema may reuse any of the identifiers without fear of name collision, although prefixes will be need to be used in an instance document to indicate which definition is actually in use.

    When referenced from an instance document one of the schemas may be defined as the default namespace to avoid identifier prefixes (e.g. the core schema) but any others must use prefixes (e.g. the extensions).

  • Have more than one namespace.

    A schema could be broken into a number of separate areas (e.g. product types, business processes, reference data type, etc) each with its own namespace and interconnected by imports. Identifiers used in any namespace may be redefined in another or in an extending schema without name collision.

    Whilst an instance document could assign the default namespace to one component of the overall schema it is more likely (for consistency) that prefixes would be assigned to all referenced schemata and every element/type prefixed to indicate its origin. To date the format of an FpML instance document has been kept simple and free of namespace prefixes. To maintain this position going forward FpML would have to either use no namespaces or a single namespace. Having no namespace would make proprietary extensions awkward to maintain as a change in the core schema could collide with an extension. Having a single namespace would mean that prefixes would only be needed whenever an extension is invoked, making them easy to identify within the document.

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

  • Only global definitions may be referenced from within other definitions.

  • Only global elements may be used as the target of a substitution group.

  • Only global elements may be used at the root for an instance document.

  • Local definitions may reuse an identifier but assign new content.

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

  • Salami Sliced

    A schema consisting of predominately global definitions.

  • Venetian Blind

    A schema in which consists of global types and local elements (except for the root element).

  • Russian Doll

    A schema in which definitions are predominately local and follow a similar structure to the instance documents.

Using global scoping establishes consistency throughout a schema although such general definitions may become too generic for some circumstances, needing additional semantic validation in the processing application. A local definition can avoid some of the generality by allowing the content to model the exact usage but such definitions cannot be used in conjunction with other features such as substitution groups or type derivation.

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

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.

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

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"/>
			

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

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

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.

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

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

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

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.

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

9.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!