Rich Service Specification (RSS)

Design by Contract

One of the important principles of SOA is design by contract, and this is one of the principles that motivates and drives the service specification. In the same way that the term contract is used in a general sense to mean a formal agreement covering some form of interchange between parties or participants, Design by Contract indicates a formal approach that covers the agreement between service provider and consumer. Design by Contract does not necessarily mean that the contract precedes development. In many cases the details of the specification will evolve over multiple iterations as the requirements are understood. However it is a prerequisite that the specification is formalized before the services is published for operational use. 

Service specification practices vary greatly. All services will have some form of specification, but many will comprise only the technical interface, that is clearly mandatory for service execution. Design by Contract infers a more rigorous form of specification and we use the term Rich Service Specification to denote a contract that comprehensively defines the required behavior and message schemas, providing all the information required by the service developer and the service consumer. 

The RSS has real benefits:

  • The specification should be independent from the implementation, allowing flexibility of implementation.
  • The service is driven by the needs of the business
  • Technical and implementation constraints are more easily applied separately from business requirements and any compromises thoroughly understood in terms of business impact
  • Business design issues are more easily separated from developer/development issues and tasks
  • The specification provides implementation independent information to the consumer to make the Service easy to use
  • The specification provides consistent detail for published APIs that use service(s)
  • The specification approach facilitates the involvement of multiple stakeholders in developing the specification
  • The specification facilitates structured approach to testing; and in many cases the test cases are developed concurrent with the specification, or even in advance to explore the service requirements. 

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 include:

  • 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 Lifecycle

The Service Specification is expected to be developed iteratively across the service life cycle states: 

  • Planned: the Service lifecycle will usually commence with a high-level description of requirements.
  • Specified: the Service is defined with precise detail of the required behaviors
  • Provisioned: the delivered Service may reflect any choices or compromises that have been made in the provisioning process, that diverge from the ideal specification
  • Deployed: in operation the Service is will publish 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 understand its purpose with the consuming solution developer 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. Everware-CBDI make the material freely available to the public under licence. Templates for various SAE deliverables are provided as Word documents. However, we do not recommend users to then complete and store instances of those documents using Word. Everware-CBDI provide a Specification Portal that stores the data in a structured manner and facilitates reuse of common specification components including rules and schema elements. The Portal integrates with modeling and schema management tools that serve the purposes of various stakeholders. ver a useful format in which to report on specifications. 


                ASF Home                     Learn More                   Service Specification

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.