An approach to implement Class specialisation in XML schemas (XSD)

23 Mar 2015, by Rodrigo Nascimento in Enterprise Architecture, Information Architecture, SOA, Sparx EA

I’ve decided to write this quick post to share a practical approach that I suggested to a client in order to solve a specific issue when realising their logical Information Model (a.k.a Canonical Model/Common Information Model/SOA Information Model…) to XML schemas (used for their Service Contracts).

Example scenario

To illustrate a specialisation scenario for a Class specialisation in XML schema, I will use a very simple example where we need to deliver an XSD for a service that will return customer and its contact methods (i.e. Telephone and Address). Below is the diagram that represents my logical model.


Realisation options

I’ve found 3 possible ways to realise specialisations from my logical information model in XSD:

  • Substitution Group – the specialisations are realised as a substitution group
  • Subsumption – using extensions to specialise complex types and XSI type reference in the XML instantiation.
  • Use of ‘Choice’ element – realise the specialisation as choice element

How does your tool behave by default?

As you would probably guess from my last post, I’ve been using Sparx Enterprise Architect as my main modelling tool. I’m also following the Object Management Group’s (OMG) Model Driven Architecture approach, with the objective to promote reusability through technology agnostic design and separation of concerns.

By default, Sparx EA maintains the generalisation associations in the physical model, resulting in the following XSD model.

If you choose the generate the XSD file at this stage (by right-clicking the schema folder and selecting Code Engineering -> Generate XML Schema), the resulting schema will represent the Subsumption option.

Which one is the right specialisation option for you?

Many technical requirements and constrains can drive your decision about the most suitable specialisation approach (i.e how does your programming language is going to deal with it? What about the visual modelling/development tools?). I don’t really want to go through the ‘pros and cons’ as it may become a very long reading (maybe endless, as it is a matter of preference and suitability).
In my case, the rationale behind the use ‘Choice’ is that it is simpler to implement (i.e. you don’t need to master Complex Type and its derivation rules) and supports full visualisation of the schema structure in visual XML modelling tools (i.e Altova XML Spy, Oxygen…) and development tools (i.e. webMethods Designer, Oracle JDeveloper…).

Using ‘Choice’ as the specialisation approach

The first step is to hide the generalisation connectors. I’m ‘hiding’ them because they are not relevant for this specific physical model, but may be to others. Also, they are recreated every time you transform your logical model (PIM) to physical (PSM).

In the next step we need to create a class with the stereotype ‘XSDchoice’. Then connect the generalisation to the choice and the later to respective specialisations.

Now you can generate the XSD file with choice element as the physicalisation of the logical class model specialisation. However…

Few Caveats

When you export the XSD file as mentioned above, you may face few common issues that will request a post-export adjustments.

1. Redundant inherited attributes and relationships

As I’ve told you to keep the hidden generalisation association, the attributes and relationships from the parent class will be present in your physical XSD file. The image below shows how the address element was generated in the XSD file.

The solution for this issue is to manually remove the derivation. In Altova XML Spy you can just delete the ‘base’ reference as shown below.

When asked about the element content preservation, just click ‘Yes’.

2. Multiples XSD files

I usually try to maintain the taxonomy of my business entities/objects based on a reference model (i.e. Information or Business Reference Model). This will define my package structure of the logical model (PIM) in Sparx EA and, consequently, will be translated into different schema packages in my physical model (PSM). This will probably result in multiple XSD files as we may want to reuse classes from different packages (i.e. Customer includes Party Role, which includes Contact Method…).
It may be suitable for some cases, but I usually use the resulting XSDs as a self-containing representation of a business object to be used as part of my service signature (mainly because they are easier to manage). In order to achieve this, I use a functionality in Altova XML Spy that creates a ‘Subset’ of the XSD model. If you want to know more about this functionality, please visit the following link:

3. Extra elements

As you probably be aware by now, the diagrams we create for both logical and physical models are just a view of the entire information model. When Sparx EA generates the physical XSD file, (unfortunately) it doesn’t consider only the diagram (view) that you’ve created. Instead, It will consider all the relationships that the classes used in your model have, resulting in a bigger XML schema.
It may not be an issue in some cases, but the only way that I’ve found to deal with this problem is to manually delete the extra elements from the XSD file.

Important Note: This post was based on the functionalities available before Sparx EA 12 was released. I’m writing another post about the new Schema Composer feature/tool in Sparx EA 12 how it supports the physical XSD realisation. As far as I could see, it promises to solve all issues mentioned above – I will update this post when I finish my tests and the respective link is available.

Rodrigo Nascimento is an experienced Enterprise and Solution Architect driven by innovation and integrity.
The combination of his passion for technology (which started when he was only 7 years old with his first ZX Spectrum) and his strong academic business background (bachelor’s degree in Marketing and MBA) has been used in many organisations to optimise the utilisation of IT resources and capabilities to leverage competitive advantage over the past 20 years.
  • […] was a helpful way to consistently produce XSD files, but it lacked few functionalities. In my ‘Approach to implement Class Specialisation’ post, I’ve described some of these gaps and the main points are listed […]

  • I started using such similar XSDChoice approach in my 2011 namespace version…