Service Oriented Architecture – A Service Contract Design Template

Registration is free. Login or register to view/download this content.


Business Relationship Manager - Product Lifecycle Management, Chevron Corporation


Service-Oriented Architecture (SOA) is a highly collaborative paradigm, and attempts to break down the invisible barriers between IT and business. A critical step to be undertaken when implementing a SOA is to identify, specify, catalog and document candidate services. Given the sheer complexity of the task, this is more of an art, rather than a science. However, there do exist some common-sense principles and best practices for this purpose. These techniques ensure consistency and more importantly, repeatability in the process, so that it can be applied holistically across the enterprise. This paper specifies one such technique.

Central to this technique is a service design template, presented in terms of a simple questionnaire, for designing, specifying and documenting a service contract. A service contract is a comprehensive description of not only the business functionality provided by the service, but also the technical design of the service along with specifications governing its usage, call semantics, service level declarations and key performance indicators (KPIs).

The over-arching goal of a service contract description document should be to develop and catalog a uniform yet multi-dimensional, enterprise-wide understanding of the purpose, scope and representation of what this service entails and involves.

Audience and Participation

It is visualized that the questions in this template are debated, discussed and “filled in” by cross-functional teams, intended to be composed of Requirements Analysts, Business Analysts, Software Architects, Developers, Management stakeholders and Operations representatives. A cross-functional team participation is deemed essential to designing a service contract, as a complement to the collaborative effort discussed before.

It must be noted that this article proposes the same document template to be utilized, iteratively, by team members with different interests and/or expertise. Design methodology gurus will recognize this to be a marked departure from traditional “waterfall” approaches, where requirements gathering and design activities were silo-ed and functionally separate, hence requiring entirely different documents. Consequently, methods had to be devised where these documents needed to be ”linked” together. This often lead to these teams working at cross-purposes with each other, and critically, essential details of the functionality implementation are lost in linking and translation.

In the new approach to service design, the “requirements-gathering” and “design” activities are visualized as concurrent activities, proceeding hand-in-hand. The resulting knowledge accumulated in these efforts is collected and collated into a single artifact (the service design document), which progressively and cumulatively gets richer in content, and endeavors to answer to all parties involved. In the end, what emerges is a comprehensive, detailed document describing the service and its features.The idea is to promote and enforce a sense of “everybody-on-the-same-page” assuredness, even before the implementation of the service is undertaken. This promotes business and technology participation and ownership in equal measure (a key goal of SOA), and enhances the likelihood that the implemented service is actually delivered and adds value to the enterprise.

Service Contract Design Template

What is the responsibility of the service?

This provides the basic description of why the service should exist. In other words, this states the basic business scope of the service. A service “does” something in terms of business significance (in other words, encapsulates business functionality). This also identifies the software component/s which implement(s) the service.

Is the service idempotent?

In other words, if a call to the service is duplicated, and instead of being called once, the service is called twice with identical parameters/payload, will the service detect the duplication and prevent any effects on the underlying systems? Risk: The implementation of such a service will be more complicated.

What pre-conditions and post-conditions apply to this service?

Similar to use case development, describe the factors that must be in place for this service to be used. Describe the behavior of the service both in the “happy path scenario” as well as when these preconditions such as state of data (incoming parameters, values discovered during course of execution, database values etc) are not met. Describe the limitations and constraints of the service.

Is the service synchronous or asynchronous?

This refers to the call semantics of the service – synchronous or asynchronous. Justify the case for either choice: is it practical for a client to wait for the service to respond? If no, there is a case for asynchronous service.

In case of a synchronous service, what are the implications of client wait-time? How long should a client wait? What is the acceptable time-out interval? What are the procedures to be followed after a time-out?

In case of an asynchronous service, the client does not have to wait for a response, but how will the client be notified of the fact that the client’s request was “serviced”? Is there a notification mechanism?

Identify the consumers of this service.

Define the actors and/or roles that a client needs to represent when calling this service. Are there multiple consumers of this service?

Does this service need to access a centralized repository to authenticate caller?

Is this service responsible for checking user/role authorizations? This is a section which caters to the service security implications, beyond the scope of this article.

What input data elements will be required in order to call the service?

This includes the actual data elements and their format definitions (XSD elements/Java Types) which the service needs in order to execute properly. More importantly, it also includes the semantic/business meaning of each element.

Is there a centralized data dictionary/format library to get these data elements from?

Will the service have to “transform” the incoming data elements to a reference, enterprise-wide canonical model?

What data elements will be returned by the service in its acknowledgement/receipt/return?Ask the same questions as above (but from an outgoing perspective). Obviously, this is important from a client’s perspective.

Does the service have transactional implications?

Does this service specify/imply a transactional context? In other words, if errors and exceptions occur during the course of execution of this service, can the client expect the data to be returned to the original state?

If this service does specify a transactional context, then is there a compensatory service which has to be invokes by the client in case of the original service failure?

When this service is deployed, do we need to plan for and implement the compensation service, so as to preserve data state integrity?

How do we determine that requirements are met by the service? What are the KPIs for this service?

This determines and specifies the benchmarks to evaluate whether the goals for this service were accomplished.

Determine bothh technical and business KPIs for this service. An example of a technical KPI would be: service performance under peak load conditions or some such metric. A business KPI example would be: Reduced order processing turn-around time by 10%.

What are the SLA elements governing this service?

Is there are QoS classification for types of clients?

Will the service be available 24×7?

What is the service level agreement that the hosting team (in our case, operations) is willing to sign up for?

If service is not available, what is the expected caller responsibility?

How is the service going to be implemented, within existing software infrastructure?Every IT organization has existing and legacy assets covering a wide variety of implementation platforms, ranging from mainframes to modern distributed applications. Therefore, a brief overview of how this specific service is going to be implemented, i.e., which of the existing assets are planned on being used in the service implementation is necessary.

If entirely new infrastructure/technology is involved, then the cost of that new paradigm needs to be factored into the overall cost of implementing the service.

Similar Resources

Featured Certificate: BPM Specialist

Everyone starts here.

You're looking for a way to improve your process improvement skills, but you're not sure where to start.

Earning your Business Process Management Specialist (BPMS) Certificate will give you the competitive advantage you need in today's world. Our courses help you deliver faster and makes projects easier.

Your skills will include building hierarchical process models, using tools to analyze and assess process performance, defining critical process metrics, using best practice principles to redesign processes, developing process improvement project plans, building a center of excellence, and establishing process governance.

The BPMS Certificate is the perfect way to show employers that you are serious about business process management. With in-depth knowledge of process improvement and management, you'll be able to take your business career to the next level.

Learn more about the BPM Specialist Certificate





  • Business Process Management Specialist
  • Earning your Business Process Management Specialist (BPMS) Certificate will provide you with a distinct competitive advantage in today’s rapidly evolving business landscape. With in-depth knowledge of process improvement and management, you’ll be able to take your business career to the next level.
  • BPM Professional Certificate
    Business Process Management Professional
  • Earning your Business Process Management Professional (BPMP) Certificate will elevate your expertise and professional standing in the field of business process management. Our BPMP Certificate is a tangible symbol of your achievement, demonstrating your in-depth knowledge of process improvement and management.


BPM Certification

  • Make the most of your hard-earned skills. Earn the respect of your peers and superiors with Business Process Management Certification from the industry's top BPM educational organization.




  • Operational Excellence Specialist
  • Earning your Operational Excellence Specialist Certificate will provide you with a distinct advantage in driving organizational excellence and achieving sustainable improvements in performance.


OpEx Professional Certificate

  • Operational Excellence Professional
  • Earn your Operational Excellence Professional Certificate and gain a competitive edge in driving organizational excellence and achieving sustainable improvements in performance.



  • Agile BPM Specialist
  • Earn your Agile BPM Specialist Certificate and gain a competitive edge in driving business process management (BPM) with agile methodologies. You’ll gain a strong understanding of how to apply agile principles and concepts to business process management initiatives.  

Business Architecture



  • Business Architecture Specialist
  • The Business Architecture Specialist (BAIS) Certificate is proof that you’ve begun your business architecture journey by committing to the industry’s most meaningful and credible business architecture training program.

  • Business Architecture Professional
  • When you earn your Business Architecture Professional (BAIP) Certificate, you will be able to design and implement a governance structure for your organization, develop and optimize business processes, and manage business information effectively.

BA CertificationCertification

  • Make the most of your hard-earned skills. Earn the respect of your peers and superiors with Business Architecture Certification from the industry's top BPM educational organization.




  • Digital Transformation Specialist
  • Earning your Digital Transformation Specialist Certificate will provide you with a distinct advantage in today’s rapidly evolving business landscape. 


  • Digital Transformation Professional
  • The Digital Transformation Professional Certificate is the first program in the industry to cover all the key pillars of Digital Transformation holistically with practical recommendations and exercises.



  • Agile Business Analysis Specialist
  • Earning your Agile Business Analysis Specialist Certificate will provide you with a distinct advantage in the world of agile software development.


  • DAS Certificate
  • Decision Automation Specialist
  • Earning your Decision Automation Certificate will empower you to excel in the dynamic field of automated decision-making, where data-driven insights are pivotal to driving business innovation and efficiency.