Design SOA services and schema definitions with SoaML and XSD transformation profiles

An easier, more architecturally oriented alternative to WSDL

Designing web services and schema definitions is a key success factor for SOA projects. This article shows how to use the Object Management Group (OMG) SoaML standard and XML schema definition (XSD) transformation UML profiles to design web services and schema definitions. The author explains why these two profiles provide an easier and more architecturally oriented way than the traditional WSDL approach.

Mohamed M. Kattaya (mkattaya@qa.gbm.ihost.com), IT Architect, GBM Qatar

author photoMohamed Kattaya is an e-business application architect working for GBM Qatar, a division of Gulf Business Machines and an IBM business partner. He previously worked for the IBM Cairo Technical Development Center (CTDC) for three years, plus he has more than 11 years of experience in IT, working on Microsoft, Oracle, and IBM products. He has a master’s degree in computer science and has participated as an architect and team lead in many SOA projects in Egypt and the Arabian Gulf. He is currently working with portal, process server, and ESBs and their related development products, including IBM Rational Software Architect and IBM WebSphere Integration Developer. He is also interested in Web 2.0 technologies and is considered an expert in UML and design patterns.



10 May 2011

Also available in Chinese

What this article covers

Service-oriented architecture (SOA) is about provided and used services. Service providers and consumers are commonly called participants. A service provider publishes descriptions of services and provides the implementation of the services. Service consumers depend on the descriptions to build service clients to invoke and consume the services. Therefore, designing the services in a proper way is important and of a high priority to the success of any SOA project.

There are three main values provided by modeling web services with UML:

  1. The first value is to abstract away any unnecessary details, such as the syntax of the Web Services Description Language (WSDL) and XML Schema Definition (XSD) and focus on the main structures of the web services, including data types in the XML schema, the operations in the web service interface, and the binding of that interface to a protocol and end point.
  2. The second value is to provide a standard way, which is a UML model, to communicate the design of the web service to both the business stakeholders and the technical team in the SOA project. Communicating the design of the web service through WSDL and XSD files to business stakeholders is not easy, especially when the number of the web services increases.
  3. The third value is to better manage and easily express the relationship between web services WSDL and XSD, such as in the composite services that combine two or more services.

These three values will be illustrated in the example presented in the article. The idea of having a modeling language for describing services has been realized since introducing the Software Services Unified Modeling Language (UML) 2.0 profile. This profile is deprecated now and replaced by Service-Oriented Architecture Modeling Language (SoaML) UML profile. It is an Object Management Group (OMG) standard that describes a UML profile and metamodel for the specification and design of services within the SOA. That profile is used in this article to design the web service interface (WSDL). The other profile used in this article is the XSD transformation UML profile, which provides stereotypes and properties for UML constructs to be generated into XML schema components.

SoaML has been supported in IBM® Rational® Software Architect for WebSphere® Software since Version 7.5.4. The example in this article is developed with Version 7.5.5. This software provides a rich set of tools and model templates for designing services artifacts using SoaML.

This article shows the main steps to design a web service, along with its XML message schema, using XSD and SoaML transformation profiles:

  1. Common schema definition design
  2. XML schema definition design
  3. Service specification or service interface definition design
  4. Service binding design
  5. Transformation configuration
  6. Model transformation into WSDL and XSD.

First, we'll introduce the example that is used to explain and apply the idea in the article.


Government SOA example in this article

A government wants to employ a government service bus that publishes services provided by some governmental agencies. These services are available to be consumed by other governmental agencies. Figure 1 shows a diagram for the example.

Figure 1. Government SOA example
ESB, services providers, and consumers interaction

The government has a common schema that is shared by all governmental agencies. Each government agency could be a provider of a service and a consumer of another service. Generic names are used in the example to avoid any accidental similarities with real names. Each governmental agency provides one service and has one XML schema. For simplicity, the example will cover creating one service with its XML schemas and a common schema, as well.

We will start with building an empty structure of the project. We assume that the agency has a subsystem on which the web service will be built. The web service is assumed to expose one functionality of this subsystem. Normally, each web service should have three artifacts:

  • XML schema or XSD
  • Specification or interface definition
  • Service or binding

This is why the folder structure that we are going to build shortly reflects that.

The following steps show how to create the UML project that will be used throughout this article:

  1. Create a UML Project with this name: soaml_example. Other than the following settings, just keep the default values of the wizard:
    1. In the Create Model tab, make sure to select General in the Categories pane and Blank Package in the Templates pane, and then write gov_agency1_serviceModel in the file name field to create a model for Government Agency Service Provider 1.
    2. In the Package Detail tab, select Model in the Package Type frame and uncheck Create a default diagram in the new package in the Default Diagram frame.
    3. In the Model Capabilities tab, check Customize UI and select Modeling, UML Diagram Building Blocks, UML Element Building Blocks, and XSD Transformation Profile, and then click Finish.
  2. Apply SoaML and XSD Transformation UML profiles to the model by following these steps:
    1. Click the gov_agency1_serviceModel model.
    2. In the Properties view, click the Profiles tab.
    3. Click Add Profile, and then, from Deployed Profile drop-down menu, select SoaML.
    4. Repeat the previous step to add XSD Transformation profile.

The Properties view of the model will look like Figure 2.

Figure 2. Properties view of the model in Rational Software Architect
UML model profiles tab of Properties view
  1. Create a package called govSrvProvider1.gov by right-clicking on the model and selecting Add UML > Package.
  2. Then, delete the freeform diagram that is created by default.
  3. Under this package, create another package called subSystem1. Under that package, create three packages: services, specifications, and xml.
  4. Then delete the freeform diagrams that are created with the packages by default.
  5. Create these packages:
    1. Under the services package, create a package called v1_0.
    2. Under the specifications package, create a package called v1_0.
    3. Under the xml package, create a package called schemas.
    4. Under the schemas package, create a package called v1_0, and then delete the freeform diagram that is created with the schemas package by default.
  6. Apply the stereotypes schema to all of the packages named v1_0 that you created in the previous step by following these steps:
    1. Click the package v1_0.
    2. Click the Stereotypes tab in the Properties view.
    3. Click Apply Stereotypes, and then select schema from the list.
  7. Import XSD primitive Data Types to the model (these primitive data types can be used to use primitive types, such as string, int, and float in the schema):
    1. Right-click on the gov_agency1_serviceModel model, and select UML Properties.
    2. Select ElementImport from the left frame and click the arrow button in the right frame.
    3. In the Search field, write XSD and select «modelLibrary» XSDDataTypes – XSDDataTypes.

The project will then look like Figure 3.

Figure 3. Project after creating model and packages for the government provider
SoaML project structure in Project Explorer view
  1. Create another model gov_commonSchema.
  2. Under this model, create the packages government.gov > commonTypes > xml > schemas > v1_0 and delete all the freeform diagrams that are created with these packages by default except the one that is with the package v1_0.
  3. Repeat step 6 and 7 for the package v1_0 and the model gov_commonSchema.

The project will look like the following figure.

Figure 4. Project after creating model and packages for all government agencies
SOAML project structure in Project Explorer view

In a real environment, for better model management and governance, the common schema should have been created in a separate project. However, for simplicity, we have everything in one project in this example.

Tips:
Creating the folder structure in a way that separates the data model, service specification, and service binding is a best practice from both source control management and development perspectives. Also, having the version number, v1_0, as part of the folder structure and namespace (as it will be shown shortly) is a governance best practice.


XML schema definition design

Messages are passing between web service providers and consumers. Messages consist of elements that have data types. These data types are defined in a schema. Before we go through the example, we will explain briefly how to create the main structures of any schema. For more information about this, see the XML schema transformation profile links in Resources. These structures are simple and complex data types. The XSD transformation profile will be used to transform the UML structures into the schema definition.

Simple data type

Applying the «SimpleType» stereotype to a UML class results in an XML schema simple type definition. Restriction of any simple type to a primitive XSD data type is possible by applying the «restriction» stereotype to a UML generalization relationship. You can manipulate any of the restriction properties of the XSD simple type in the XSD SimpleType tab of the Properties view. Primitive data types were imported into the model in the previous steps of creating the project and model. As an example of manipulating the properties of a simple data type, in the EmailAddressType simple type, the pattern value is set to this, as shown in the figure that follows:

[0-9A-Za-z'\.\-_]{1,127}@[0-9A-Za-z'\.\-_]{1,127}
Figure 5. XSD simple type in UML
Class diagram for XSD simple type

When transformed into XSD, that figure looks like the code in Listing 1.

Listing 1. XSD simple type in XML
<xsd:simpleType name="EmailAddressType">
    <xsd:restriction base="xsd:string">
      <xsd:pattern value="[0-9A-Za-z'\.\-_]{1,127}@[0-9A-Za-z'\.\- _]{1,127}"/>
    </xsd:restriction>
  </xsd:simpleType>

Enumeration

Enumeration is a special type of the simple type. It is needed when there should be a specific list of constant values to be used for the simple type defined by the enumeration. A common example of enumeration for gender is shown in the following figure.

Figure 6. XSD enumeration in UML
Class diagram for XSD enumeration type

When transformed into XSD, that looks like the following code.

Listing 2. XSD enumeration in XML
<xsd:simpleType name="GenderType">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value="MALE"/>
      <xsd:enumeration value="FEMALE"/>
    </xsd:restriction>
  </xsd:simpleType>

Complex data type

To create a complex type, a «complexType» stereotype must be applied to a UML class (see the next figure). The properties of the complex type can be manipulated in the XSD Complex Type tab of the Properties view. You can add elements to the complex type by adding attributes with the «element» stereotype to the UML class. These attributes are either added directly by primitive XSD data types or associated by other types defined in user-specific schemas.

Note:
The minOccurs attribute of any element can be specified by setting the Multiplicity of the attribute.

Figure 7. XSD complex type in UML
Class diagram for XSD Complex Type

Listing 3 shows this model the XSD.

Listing 3. XSD complex type in XML
<xsd:complexType name="PersonInfoType">
    <xsd:sequence>
      <xsd:element name="ID" type="xsd:string"/>
      <xsd:element name="personName" type="xsd:string"/>
      <xsd:element minOccurs="0" name="emailAddress" type="govxsd:EmailAddressType"/>
      <xsd:element name="gender" type="govxsd:GenderType"/>
    </xsd:sequence>
  </xsd:complexType>

Common schema definition

The common schema defines the XSD data types that are shared between all participants in the SOA project, thus all other government agencies in this example. The common schema has one major advantage of having all common data types defined away from any specific service provider. This allows for more control and governance on these common types and minimizes the interdependencies between the service providers' schemas. However, the common schema has one major disadvantage: any update to the common schema requires synchronization with all service participants that depend on it. Creating the schema in UML is just creation of a class diagram and applying the appropriate stereotypes, as explained before. The following figure depicts the common schema in the example presented in the article.

Figure 8. XSD common schema example
Class diagram for SoaML example XSD common schema

Note:
The whole set of schema properties are available in the XSD Schema tab in the Properties view. In the example, only three of the properties have been set, as the following figure shows.

Figure 9. XSD schema properties
Common XSD schema tab of the Properties view

To change these properties:

Under the gov_commonSchema project, select the schema v1_0 under government.gov > commonTypes > xml > schemas > v1_0, and set the properties in the XSD Schema tab in the Properties view:

  1. Element from Default to qualified
  2. Target Namespace to urn:government.gov/commonTypes/xml/schemas/v1_0/
  3. Target Namespace Prefix to govxsd

Tips:
It is a good practice to have the Target Namespace follow the same package structure of your schema. Also, documentation can be added to the schema or any data type or element in the schema through the Documentation tab in the Properties view. The schema model in the project structure will look like the following screen capture.

Figure 10. Common schema model view in the Project Explorer
Directory (tree) view

Web service XML schema definition design

Now it is time to start working on the web service artifacts. Normally, this activity starts with creating the web service schema definition, and then creating the web service WSDL definition or the web service interface, and, finally, creating the web service WSDL binding. The web service that is presented in our example, which is the web service that is provided by the Government Agency Service Provider 1, is about getting the birth certificate of a person. The schema of this service is depicted in the following figure.

Figure 11. XSD schema of Government Agency 1, service example
Class diagram for XSD of the agency in the example

Larger view of Figure 11.

Again, creating the schema in UML is just creation of a class diagram with applying the appropriate stereotypes. As before with the common schema definition, you need to set three properties of the schema..

  1. To change these properties, in the gov_agency1_serviceModel project, under govSrvProvider1.gov > subSystem1 > xml > schemas > v1_0, click the v1_0 schema , and set these properties in the XSD Schema tab in the Properties view:
    1. Element from default to qualified
    2. Target Namespace to urn:govSrvProvider1.gov/subSystem1/xml/schemas/v1_0/
    3. Target Namespace Prefix to govprv1xsd

Web service specification design

Now, it is time to build the WSDL interface definition of the web service. It is always best to separate the web service interface definition, which is the WSDL port type, from the web service WSDL binding. A binding defines message format and protocol details for operations and messages defined by a particular WSDL port type. Besides the separation of concerns, that separation of WSDL port type from the WSDL binding in two documents allows for any number of bindings for a given port type. The following steps show how to create a web service WSDL port type in UML.

  1. Under govSrvProvider1.gov > specifications > v1_0, open the Main freeform diagram
  2. To add a web service interface, from the Service tray in the Palette, click the Service Interface (simple) and click the diagram. Then name it BirthCertificateInfo.
  3. Add an operation to this interface normally, like adding any operation to a UML interface, and then name it getBirthCertById.
  4. Create messages for the operation that you just created. The purpose of the messages is to wrap whatever input or output parameters to the operation in one request message and one response message.
    1. From the Class tray in the Palette, click the Stereotyped Class and click the diagram. Then select Create «MessageType» Class from the drop-down menu, and name it getBirthCertByIdRequest.
    2. Repeat the previous step to create another message with the name getBirthCertByIdResponse.
    3. Add an attribute to getBirthCertByIdRequest and name it ID. Set its type to string and add the «element» stereotype to it.
    4. Add an attribute to getBirthCertByIdResponse, and name it birthcertificate. Set its type to BirthCertificate from the schema of the service, and add the «element» stereotype to it.
  5. Click on the interface that you just created and, in the Operations tab in the Properties view.
  6. Click the Owned Parameter button and, when a pop-up window opens, click the Insert New Parameter button three times to add three parameters.
    1. The first parameter is the input parameter to the operation. For the first parameter, change its Name to Id, and set its Type to getBirthCertByIdRequest, which can be done by typing in the Search field. Tip: You might need to scroll right to set the properties of this parameter.
    2. The second parameter is the output parameter of the operation. Change its Name tobirthCert, set its Direction to Return, and set its Type to getBirthCertByIdResponse by typing in the Search field. Tip: You might need to scroll right to set the properties of this parameter.
    3. The third parameter is the exception of the operation. Change its Name to fault, set its Direction to Return, set Is Exception to true, and then click Browse and select government.gov > commonTypes > xml > schemas > v1_0. Set the parameter Type to ExceptionType.
  7. Select govSrvProvider1.gov > xml > schemas, and then click the v1_0 schema to set the following properties in the XSD Schema tab in the Properties view:
    1. Element from Default to qualified
    2. Target Namespace to urn:govSrvProvider1.gov/subSystem1/specifications/v1_0/
    3. Target Namespace Prefix to srvspc1xsd

The web service interface will then look like the following figure.

Figure 12. Web service WSDL interface UML example
Class diagram for WSDL interface of example agency

The web service interface is now complete, so you can define any binding to that interface.


Web service binding design

Now it is time to specify binding for the WSDL interface of the web service. The binding references the port type that it binds. To add a binding in this example, follow these steps:

  1. Select govSrvProvider1.gov > services > v1_0,open the Main freeform diagram.
  2. From the Service tray in the Palette, click on a Participant and then click the diagram. Name it BirthCertificateInfoService.
  3. In the Project Explorer, right-click on «Participant» BirthCertificateInfoService and select Add Service Modeling > Service Point. Then click Select Existing Element and search for «ServiceInterface»BirthCertificateInfo and select it. After that, name it BirthCertificateInfoPort.

The web service WSDL binding component will then look like the following figure.

Figure 13. Web service WSDL binding UML example
Class diagram for WSDL binding of the agency

After the UML model for the web service is ready, it is time to transform this UML model to WSDL and XSD artifacts. To do that, you need to create a transformation configuration.


Transformation configuration

It is always best to have two different transformation configurations: one for WSDL and the second for XSD. This is to give you better change management on the WSDL and XSD, separately. For example, most of the time, there is a change in the schema, and then the XSD has to be updated without any change to the WSDL. So, for this example, you will create three transformation configuration files:

  • One for UML to XSD for the common schema
  • Another one for UML to XSD for the government agency
  • The last one for UML to WSDL for the government agency

UML- to-XSD transformation configuration

Start with the steps to create a UML-to-XSD transformation configuration for the common schema:

  1. Create a folder, and name it WSDL by right-click on the project and selecting New > Folder. This folder is to contain the WSDL and XSD files that will be generated.
  2. To create a transformation configuration, click Modeling > Transform > New Configuration in the menu. Name it gov_commonSchema_uml2xsdV1_0, and from the Service Oriented Architecture Transformations folder, select UML to XSD from the Transformation menu. Then, click Next.
  3. From the Source and Target page, in the Selected source menu, select «schema» v1_0 from gov_commonSchema>government.gov>commonTypes>xml>schemas. Next, select the WSDL folder in the Selected target menu. Then click Finish. The gov_commonSchema_uml2xsdV1_0.tc file is created and opened.
  4. In the Main tab, in Merge options, select the Do not merge: Warn before overwriting any files option.
  5. In the Output Options tab, select v1_0 in the File Name column of the table. Then, uncheck the Add suffix check box and in the Add prefix field, write commonSchema, so the file name will be commonSchema_v1_0. Click the desk icon or press Control + s to save the file.

Repeat the previous steps with the appropriate source and target to create a transformation configuration with the name gov_agency1Schema_uml2xsdV1_0.tc for the schema of the service of the government agency, with the schema file name of govAgency_srvSchema_v1_0.

Service transformation configuration

Now, let us create a transformation configuration for the service itself:

  1. Click Modeling > Transform > New Configuration in the menu. Name the configuration gov_agencyPrv_Srv1_uml2wsdlV1_0, and from the Transformation menu from the Service Oriented Architecture Transformations folder, select UML to WSDL. Then click Next.
  2. From the Source and Target page, in the Selected source menu, from gov_agency1_serviceModel>govSrvProvider1.gov>subSystem1>services>v1_0, select «Participant» BirthCertificateInfoService.. Next select the WSDL folder in the Selected target menu. Then click Finish. The gov_agencyPrv_Srv1_uml2wsdlV1_0.tc file is created and opened.
  3. In the Main tab, in Merge options, select Do not merge: Warn before overwriting any files.
  4. In the Output Options tab, do the following:
    1. Select BirthCertificateInfoService in the File Name column of the table, uncheck the Add prefix check box, and in the Add suffix field, write _v1_0.
    2. Select v1_0 in the File Name column of the table that corresponds to specifications. Then uncheck the Add suffix check box and in the Add prefix field, write BirthCertificateInfo, so the file name will be BirthCertificateInfo_v1_0.
    3. Select v1_0 in the File Name column of the table that corresponds to subsystem/xml/schema. Then uncheck the Add suffix check box and write in the Add prefix field, write govAgency_srvSchema, so the file name will be govAgency_srvSchema_v1_0.
    4. Select v1_0 in the File Name column of the table that corresponds to commonTypes. Then uncheck the Add suffix check box and in the Add prefix field, write commonSchema, so the file name will be commonSchema_v1_0. Click the desk icon or press Control + s to save the file.

The web service model in the Project Explorer will look like the next figure.

Figure 14. Government Agency 1 service example Project Explorer view
Directory (tree) screen capture

Transforming the web service model into WSDL and XSD

It is preferable to transform the common schema before the service artifacts, because the later depends on the former. So, to transform the model into the WSDL and XSD files, follow these steps:

  1. Open gov_commonSchema_uml2xsdV1_0 if it is not open.
  2. Click the Run button.

A file named commonSchema_v1_0.xsd, along with the folder structure government > gov > commonTypes > xml > schemas > v1_0, will be created.

Following similar steps with gov_agency1Schema_uml2xsdV1_0.tc and gov_agencyPrv_Srv1_uml2wsdlV1_0.tc will lead to creation of BirthCertificateInfo_v1_0.wsdl and BirthCertificateInfoService_v1_0.wsdl, respectively.

Note:
Running the transformation configuration again will prompt you for replacing the output file, because you selected the Do not merge: Warn before overwriting any files option in the Merge options in the steps for creating the transformation configuration.


Summary

Using an example, this article presented a practical way of designing web services and schema definitions for SOA projects by using SoaML and XSD transformation UML profiles. This way can be used by architects and developers who want to build web services in a top-down approach, using UML, and abstract away from the details of XML. You now know the necessary steps of modeling a web service and its data model.


Download

DescriptionNameSize
SoaML exampledesign-soa-services-schema-definitions.zip23KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=657213
ArticleTitle=Design SOA services and schema definitions with SoaML and XSD transformation profiles
publish-date=05102011