Service oriented architecture Modeling Language (SoaML) – Introduction


Service Oriented Architecture (SOA) is a paradigm for defining how people, organizations and systems provide and use services to achieve results.

The Service oriented architecture Modeling Language (SoaML) provides a metamodel for specifying and designing services within a service-oriented architecture. 1

The SoaML extends the capabilities of the Unified Modeling Language (UML) to support:

  • Identifying services, the requirements they are intended to fulfill, and the anticipated dependencies between them
  • Specifying services, including the functional capabilities they provide, what capabilities consumers are expected to provide, the protocols or rules for using them, and the service information exchanged between consumers and providers
  • Defining service consumers and providers, what requisition and services they consume and provide, how they are connected, and how the service functional capabilities are used by consumers and implemented by providers in a manner consistent with both the service specification protocols and fulfilled requirements
  • The policies for using and providing services
  • The ability to define classification schemes having aspects to support a broad range of architectural, organizational, and physical partitioning schemes and constraints
  • Defining service and service usage requirements, and linking them to related metamodels, e.g. the Business Motivation Model (BMM), the UML UseCase model

Previous: SOA-O Event Class
Next: SOA-3 Overview


Next: Identifying services

  1. The SoaML focuses on basic service modeling concepts. The intention is to use this as a foundation for further extensions both related to integration with other metamodels like the Ontology Definition Metamodel (ODM), the Organization Structure Metamodel (OSM), the Semantics of Business Vocabulary and Business Rules (SBVR), the Business Process Definition Metamodel (BPDM), and the Business Process Model Notation (BPMN).

Jim Amsden – Service oriented architecture Modeling Language (SoaML)

Jim Amsden is Senior Technical Staff Member, IBM. His papers provide a nice introduction to SoaML – a technology I’ll be using to visualize a vocabulary of Government Services derived from

Modeling with SoaML (2010)

Using SoaML Services Architecture (2012)

Integrating BPMN and SoaML (2014)


SoaML – Identifying services


SOA strives to be business-relevant – driven by the business and implemented to support the business. SOA solutions need to be connected to the business requirements that they fulfill. We need a way to formalize business requirements so that SOA can more closely resemble business services and how those services might meet business objectives – this ties the deployed SOA solution to its intended business value. We also need a way to isolate business concerns from the evolving SOA platforms that support them.

Models allow us to abstract away from the implementation details and focus on the issues that drive business and architectural decisions.

Usually one begins by describing the business motivation that establishes the business objectives. One then models high-level business processes that are business requirements to meet the objectives. We are now ready to create a model to meet these requirements – by identifying capabilities, exposing appropriate candidate capabilities as services, and then defining the architecture for how the services interact.

To identify services, one treats the business process as a Service Requirement contract – then service specifications and service providers are designed and connected together in a manner that fulfills the business requirements while addressing software architectural concerns.

This process of identifying candidate services from a business model is also known as domain decomposition.

SoaML provides several ways of identifying services. The requirements from the business process could be viewed as a service architecture, thus indicating the participants in the business processes, the service contracts that specify how they interact, and the choreography of their services and requests.

A service architecture is a formal specification of the business requirements that are performed by interacting service participants.

The example we will use in our series on SoaML is based on the Purchase Order Process example taken from the OMG SoaML standard, and it is based in the BEPL 1.1 specification.

Scenario: A consortium of companies has decided to collaborate to produce a reusable service for processing purchase orders. These are the goals of the project:

  • Establish a common means of processing purchase orders
  • Ensure that orders are processed in a timely manner and deliver the required goods
  • Help minimize stock on hand and inventory maintenance costs
  • Minimize production and shipping costs

We will skip over the discussion of how to identify services in Amsden’s original article, as our primary interest is using SoaML to model a vocabulary of government service, including a vocabulary derived from

There are five main packages in the PurchaseOrderProcess model:

  1. org::ordermanagement – contains elements concerned with order management
  2. org::crm – contains the data model and common interfaces for some envisioned customer
  3. com::acme::credit – contains elements concerned with invoicing and credit management
  4. com::acme::productions – contains elements that are concerned with productions and scheduling
  5. com::acme::shipping – contains elements concerned with shipping

These packages divide the problem domain into different functional areas. This helps manage complexity, establishes required name spaces, facilitates reuse, and keeps separate concerns in different packages. Here’s the package dependencies diagram for our service model:

SoaML - package dependencies in service model of processing purchasing orders

This organization could be called the dominant organization of the service model. Perspective packages can be used to document other ways of organizing the same model elements.

Service identification consists of determining which capabilities should be exposed as services. The IBM SOMA method provides a Service Litmus Test that can be applied to capabilities to determine which ones should be exposed as services. The Service Litmus Test examines each capability and applies various configurable metrics to determine which one(s) should be exposed as services. See RUP for SOMA for details.

We close with Amsden’s figure that shows the service architecture for processing purchase orders at the end of the exercise of identifying services:

Service architecture for processing purchase orders



SoaML may be used to identify services that are connected to business requirements:

  • capture the business objectives necessary to realize the business mission
  • model the business processes that are necessary to meet the business objectives
  • use the business requirements and business processes to identify the required capabilities and the potential relationships between them

Capabilities are treated as candidate services. The capabilities that passed the service litmus test were used to identify the required service interfaces. This ties the service interfaces back to the business requirements.

The result is a formal structure for identifying business-relevant capabilities that are linked to the business objectives that that they are intended to fulfill.

Previous: Service oriented architecture Modeling Language

Next: SoaML – Specifying services

SoaML – Specifying services

In a previous post, we outlined an approach for identifying services that are connected to the business requirements of an enterprise.

Here we will model the specification of each service in detail. These specifications define the interfaces between consumers and producers of the service. These contracts include the provided and required interfaces, the roles that those interfaces play in the service specification, and the rules or protocols for how those roles interact.

Overview of service specifications

A service interface must specify everything that a potential consumer of the service needs:

  • to decide whether they are interested in using the service
  • to know how to use it

A service interface must also specify everything that a provider of the service needs:

  • to know to implement the service successfully

At the heart of SOA is the construction of service value chains that connect user needs with compatible provider capabilities.

A service interface defines the goals, needs, and expectations of user participants (i.e. consumers) as well as the value propositions, capabilities, and commitments of provider participants. Therefore, they provide the information necessary to determine compatible needs and capabilities.

A service interface includes:

  • The name of the service, suggesting its purpose
  • The provided and required interfaces, thereby defining the functional capabilities that are provided by the service and those that it requires of its users – Note: this is not about how the service is implemented, but rather the interaction between the consumers and providers of this service. Each functional capability includes:
    • Its name, which is often a verb phrase indicating what it does
    • Any required or optional service data inputs and outputs
    • Any pre-conditions that consumers are expected to meet before using the capability
    • Any post-conditions that consumers can expect and that providers must provide upon successful use of the capability
  • Any communication protocol or rule that specifies rules for how the functional capabilities are used or in what order
  • Any capabilities that consumers are expected to provide to be able to use or interact with the service
  • Requirements that any implementer must meet when providing the service
  • Constraints that reflect what successful use of the service is intended to accomplish and how it will be evaluated
  • Qualities that service consumers should expect and that providers are expected to provide, such as cost, availability, performance, footprint, suitability to the task, competitive information, etc
  • Policies for using the service, such as security and transaction scopes for maintaining security and integrity or for recovering from the inability to successfully perform the service or any required service

Qualities that service consumers should expect and policies for using a service may be specific to particular providers of a service, not the interface of a particular service itself.

A service interface tells you everything you need to know about a service – including the requirements that you have to meet to use the service (sometimes called the Use or Usage contract (see Daniels and Cheesman article), plus the requirements that an implementer of the service has to meet (sometimes called the Realization contract). This is the same information that we needed to capture for the business requirements, except that the subject area and level of detail are different.


Returning to our example, Figure 1 shows the service interfaces that expose the capabilities required for processing purchase orders:

SoaML Specifying services - Capabilities


Figure 1.

Let’s elaborate on each of the identified service specifications in Figure 1. The presentation order is from a very simple service interface that has no protocol, to a service interface that represents a simple request-response protocol, to a more complex service interface that involves a multi-step protocol and interaction between the user and provider.

Scheduling service interface

The Scheduling service interface shown in Figure 2 is very simple.

SoaML Specifying services - Scheduling service interface

Figure 2.

The service provides two operations: the ability to respond to a production schedule request and the ability to create a shipping schedule. These operations were created by examining the functions of the capabilities the service interface is exposing. As far as we know, in this situation there is no protocol for using these operations. Either can be used in any order.

The Scheduling service interface is a simple UML interface defined in the productions package. It provides two service operations. Each of these operations can have pre-conditions and post-conditions, and they can raise exceptions. The parameters of the service operations are required to be either service data (DataType or MessageType) or primitive types. This ensures that the parameters make no assumptions about call-by-reference or call-by-value, where the service data is located (in what address space), whether the service user or provider is operating on a copy of the data or some persistent data source, and so on. All of this is required to ensure that the service is not constrained by where it can be deployed in relation to other services. The service data is defined below.

Shipping service