SOA-RM – Service description

In support of the dynamics of interacting with services are a set of concepts that are about services themselves. These are the service description, the execution context of the service and the contracts and policies that relate to services and service participants.

SOA-RM - About services

Figure 1. About services.

Service description

One of the hallmarks of a Service Oriented Architecture is the large amount of associated documentation and description.

The service description represents the information needed in order to use a service. In most cases, there is no one “right” description but rather the elements of description required depend on the context and the needs of the parties using the associated entity. While there are certain elements that are likely to be part of any service description, most notably the information model, many elements such as function and policy may vary.

SOA-RM  - Service description

Figure 2. Service description.

The purpose of description is to facilitate interaction and visibility, particularly when the participants are in different ownership domains, between participants in service interactions. By providing descriptions, it makes it possible for potential participants to construct systems that use services and even offer compatible services.

For example, descriptions allow participants to discriminate amongst possible choices for service interaction; such as whether the service provides required capabilities, how to access the service, and negotiate over specific service functionality. In addition, descriptions can be used to support the management of services, both from the service provider’s perspective and the service consumer’s perspective.

Best practice suggests that the service description SHOULD be represented using a standard, referenceable format. Such a format facilitates the use of common processing tools (such as discovery engines) that can capitalize on the service description.

While the concept of a SOA supports use of a service without the service consumer needing to know the details of the service implementation, the service description makes available critical information that a consumer needs in order to decide whether or not to use a service.  In particular, a service consumer needs to possess the following items of information:

  1. That the service exists and is reachable;
  2. That the service performs a certain function or set of functions;
  3. That the service operates under a specified set of constraints and policies;
  4. That the service will (to some implicit or explicit extent) comply with policies as prescribed by the service consumer;
  5. How to interact with the service in order to achieve the required objectives, including the format and content of information exchanged between the service and the consumer and the sequences of information exchange that may be expected.

While each of these items SHOULD be represented in any service description, the details can be included through references (links) to external sources and are NOT REQUIRED to be incorporated explicitly.  This enables reuse of standard definitions, such as for functionality or policies.

Other sections of this document deal with these aspects of a service, but the following subsections discuss important elements as these relate to the service description itself.

Service reachability

Reachability is an inherently pairwise relationship between service providers and service consumers. However, a service description SHOULD include sufficient data to enable a service consumer and service provider to interact with each other. This MAY include metadata such as the location of the service and what information protocols it supports and requires. It MAY also include dynamic information about the service, such as whether it is currently available.

Service functionality

A service description SHOULD unambiguously express the function(s) of the service and the real world effects (see Section 3.2.3) that result from it being invoked.  This portion of the description SHOULD be expressed in a way that is generally understandable by service consumers but able to accommodate a vocabulary that is sufficiently expressive for the domain for which the service provides its functionality.  The description of functionality may include, among other possibilities, a textual description intended for human consumption or identifiers or keywords referenced to specific machine-processable definitions.  For a full description, it MAY indicate multiple identifiers or keywords from a number of different collections of definitions.

Part of the description of functionality may include underlying technical assumptions that determine the limits of functionality exposed by the service or of the underlying capability.  If the assumptions are not valid, the user may need to use another service to access the capability.

Policies related to a service

A service description MAY include support for associating policies with a service and providing necessary information for prospective consumers to evaluate if a service will act in a manner consistent with the consumer’s constraints.

Service interface

The service interface is the means for interacting with a service.  It includes the specific protocols, commands, and information exchange by which actions are initiated that result in the real world effects as specified through the service functionality portion of the service description.

The specifics of the interface SHOULD be syntactically represented in a standard referenceable format. These prescribe what information needs to be provided to the service in order to access its capabilities and interpret responses.  This is often referred to as the service’s information model.  It should be noted that the particulars of the interface format are beyond the scope of the reference model. However, the existence of interfaces and accessible descriptions of those interfaces are fundamental to the SOA concept.

While this discussion refers to a standard referenceable syntax for service descriptions, it is not specified how the consumer accesses the interface definition nor how the service itself is accessed.  However, it is assumed that for a service to be usable, its interface MUST be represented in a format that allows interpretation of the interface information by its consumers.

The limits of description

There are well-known theoretic limits on the effectiveness of descriptions – it is simply not possible to specify, completely and unambiguously, the precise semantics of and all related information about a service.

There will always be unstated assumptions made by the describer of a service that must be implicitly shared by readers of the description. This applies to machine processable descriptions as well as to human readable descriptions.

Fortunately, complete precision is not necessary – what is required is sufficient scope and precision to support intended use.

Another kind of limit of service descriptions is more straightforward: whenever a repository is searched using any kind of query there is always the potential for zero or more responses – no matter how complete the search queries or the available descriptions appear to be. This is inherent in the principles involved in search.

In the case that there is more than one response, this set of responses has to be converted into a single choice. This is a private choice that must be made by the consumer of the search information.

Previous: SOA-RM – Real world effect
Next: SOA-RM – Policies related to a service