Artifact: Service Specification
This artifact is a model element that provides both the structural and behavioral specification for a service instance. A service specification also may identify a set of policies governing the access to a service or use of the service. This specification acts as a contract between the service client and service implementer; the client understands how to interact with a service and the implementer understands the behavior expected of the implementation.
Work Product Kinds: Model Element

The following people use the service interface:

  • Implementers of the services, for an understanding of the interface the service provides, but also the behavior its clients expect.
  • Implementers of service clients, for an understanding of the interface the service provides, but also how the service expects to be interacted with.
  • Designers of services, in understanding the relationship between specifications and the relationship between services and the specifications they implement.
  • Those who design the next version of the system, to understand the functionality in the service model.
  • Those who test the classes, to plan testing tasks.

The service specification has to provide both the provider (implementer) of a service and the consumer of a service with a reasonable and complete specification of the following aspects:

  • Interface Specification; this specifies the set of operations provided by a service realizing this specification. Each operation is named and provides a signature composed of input, output, and exception messages.
  • Behavioral Specification; this specifies the protocol between the service and the consumer. A service may be stateful (either explicit or implicit - see the guideline State Management for Services) or it may have certain conversational requirements fulfilled by the client.
  • Policy Specification; this specifies constraints and policies regarding the operation of the service. Examples of policies include security (see Task: Identify Security Patterns), availability, quality of service and so on; these also represent non-functional requirements of the solution as a whole.
  • Variability Specification; this specifies how the service is configured for deployment and how it can support generic use cases through variability in it's behavior both dynamically (messages at runtime) and statically (through configuration parameters).
Container Artifact
RolesResponsible: Modified By:
TasksInput To: Output From:
Process Usage
Main Description

The use of an interface denotes a set of operations provided by a service. Note that a service may implement more than one interface. By convention it is possible to attach a protocol state machine or UML 2.0 Collaboration to such a specification to denote the order of invocation of operations on a service specification. With such a behavioral specification any implementing service can be validated against not only a static but dynamic specification of its structure and behavior.

The use of a class allows for a specification to directly denote a set of required as well as provided capabilities as a complete unit.

Note that the service specification may only provide public features. The ability to include properties on a service specification allows for the modeling of resources.

The specification has a property 'status' that is used to represent a concept common across the SOA methodologies; that of a distinct lifecycle for service descriptions. In the profile an enumeration is used to capture these common values, as listed below.

  • Candidate (default) -- denotes that the service specification has been created from some identification task but has yet to be formally accepted. Acceptance can include passing certain tests (SOMA), alignment with the enterprise service portfolio (RUP/SOA), etc. 
  • Accepted -- denotes that a service has moved from a candidate status to accepted, though this simply implies that the service will be developed, the scope of the service has yet to be determined.
  • Exposed -- denotes that the service is to be exposed outside of its immediate scope. This implies the service is to be made available for reuse, it does not specify the particular scope, this should not be read as 'public on the Internet' for example.

Also the property 'source' allows the designer to denote which technique or source domain was used to identify this service. See Task: Business Process Analysis, Task: Data Model Analysis, Task: Existing Asset Analysis, Task: Business Rule Analysis, and Task: Business Use Case Analysis (SOA).

Representation OptionsUML Representation:

Interface or Class, stereotyped as <<Service Specification>>. A specification should also provide either a protocol state machine or collaboration that documents its behavioral specification.


  • status : SpecificationStatus - denotes a service specification as a candidate service, that is a service that has been identified but not yet qualified for development.
  • source : String - this property is used to capture the 'method' or technique used to identify the service specification.

When a Class is being used as the representation for a Service Specification the class should NOT include any behavior.

More Information