Rich Service Specification

Contract-First Delivery

One of the important principles of SOA is that of contract-first delivery, and this is one of the principles that motivates and drives the service specification.

Contract-first means the specification of the service should precede development of the automation unit (its implementation). In simple terms, the steps should be to,

  1. document the specification of the service
  2. from this, produce the service definition language file, using for example WSDL, to define the service endpoint
  3. and then build the implementation

Even where the automation unit and its technical interfaces already exist, for example in a current system - the service should still be specified in a contract-first approach, documenting the required behavior and message schemas, and not simply reflecting the behavior already provided by the automation unit.

The task for the developer is to then map the Service Endpoint to the existing technical interface, which may require some transformation to take place, if only to convert the data types in the technical interface to those in the message schema.

In this way, the Service now becomes independent of the automation unit, and different transformations if needed, can be used to link the service to alternative implementations.

Used in Multiple-Roles

In order to use a Service, the Service Consumer will of course want to know exactly what the service does. They will want to know what behaviour it offers, and what they have to do in order to use the Service.

A Service Provisioner whose role it is to locate a suitable Service will need to be able to compare the available Services against a specification to see if it meets requirements. Or if they are commisioning a new Service (or implementation of) they will need to precisely detail the required behavior of that Service.

Hence, the developer in the Service Providing organization who has to build an implementation of the Service also needs to know what requirements need to be meet.

A Service Specification is an implementation-neutral deliverable that contains all the information necessary to meet all these needs.

The Service Specification facilitates exchange of consistent and precise instructions between different participants in the Service supply chain.

Rich Service Specification Sections

To address these needs, the Service Specification must provide a thorough description of what a service does, to avoid having to reveal how it is realized or deployed. The sections in the CBDI-SAE Rich Service Specification includes

  • Service properties that provides basic information on the status and history of the service
  • Business properties that show how the Service supports the business, and who in the business is responsible for the Service
  • Technical properties that provide a more IT-centric view of the Service
  • Quality of service that is or should be offered by the Service – such as the reliability or security requirements

At a more detailed level, the Service Specification details

  • Functional behavior of the individual operations, including the operation signature, together with the pre and post conditions that must be met by the provider and consumer
  • Details on message exchange
  • A Service Information Model that details the information that is stored or retrieved by the Service.

Service Specification and the Service Lifecyle

The Service Specification is expected to be developed iteratively across the service life cycle. For example, as a

  • Planned Service it may start as a high-level description of requirements.
  • Specified Service it will provide precise detail of the required behaviour
  • Provisioned Service is may reflect any choices or compromises that have been made in the provisioning process, that diverge from the ideal specification
  • Deployed Service is will detail the actual endpoints and other aspects required to use the service at runtime

The CBDI-SAE meta model for SOA shows a 1 to many relationship between a "notional" Service (e.g. the concept that is meaningful to the business) and the Service Specification.

This allows for versions or variants. For example an organization may allow variants of the Service Specification in order to serve the different needs of different parts of the business. Notionally they are all the same service at a business level, and so the organization needs to trace the Service Specification variants all back to that same business service.

Also, an organization may wish to keep a copy of the specification that details their 'ideal' requirement, even though the provisioned service might make compromises to that, and hence has a different specification. But that doesn't require two different templates - one covering 'requirements' and another for 'operational' Services - rather it requires two separate but related instances.

They key thing is that participants are then using the relevant instance and understands its purpose. e.g., the consuming solution developer is working from the service specification instance that reflects the provisioned, operational Service, and not on the instance that was a statement of ideal requirements.

Ideally, Service Specifications are not stand-alone documents, but entries in a Service Catalog that can maintain all these relationships, understands their current state(s), and ensures that their visibility is relevant to the role/task of the participant.

Using the Rich Service Specification Template

A PDF version of the CBDI-SAE Rich Service Specification Template is available for download. We are making the material freely available to the public under licence.

CBDI provides templates for various SAE deliverables as Word documents. However, we do not really expect users to then complete and store instances of those documents using Word. Rather, they should treat them as the basis for schemas from which they could create a database to store the data in a more structured way – for example in some form of Service Catalog. Our Word templates might then be better used as a format in which to report from that database, rather than the place in which the data is itself stored.

For example, the Operation Signatures would be held as WSDL documents, and the Service Information Model might be held as a UML Class diagram in a modelling tool. Further guidance on this is provided in various CBDI Journal Reports

The Rich Service Specification is provided free for download to registered members.

Resources and Downloads

Rich Service Specification Template for SOA (pdf)

Provides a SOA Deliverable template for the documentation of a rich service specification in SOA Projects. The Service Specification provides the definition of what a service does - in terms of behavior, information and nonfunctionals - regardless of how it is realized or deployed.

Service Contracts in the Service Oriented Process (pdf)

At the heart of the service concept is conformance with the principle of the "contract based" capability. Whilst many SOA principles will be optional depending upon context, the use of service contracts is likely to be required, because a well formed service is likely to be the primary enabler of the agile business. At the same time it is important to use a pragmatic level of specification detail that is appropriate to the context of use. Our practice research to date has focused on the Rich Service Specification and the Service Level Agreement. In this report we extend that guidance to cover evolution of specification artifacts across the full service life cycle, in an integrated way, to include all the involved parties.

Service Specification Reference Framework. An Overview

This research note explores aspects of a reference model for service specification, outlining several important concepts.

Service Specification Survey Results

Services are progressively becoming the de facto architecture for the enterprise. Whether a service is implemented as a REST API or SOAP Web Service, a specification of some sort is essential for the delivery and operational life cycle management. Casual observation tells us that service specification approaches in common use are highly variable. In our survey, conducted in October 2013 we asked architects, designers and project managers to tell us how they deliver and use service specifications. The results substantiate preconceptions to some extent, but also highlight some very interesting issues.


You must confirm your screen name on your profile in order to comment.

Please sign in if you wish to comment.