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