Working towards the next version of the SWIM Supporting Material
Working towards the next version of the SWIM Supporting Material
Version
This page concerns v2.0 of the Specification. Supporting material on v1.0 is SWIM-SERV-001 Description coverage.
Requirement
Title | Service description coverage |
Identifier | SWIM-SERV-010 |
Requirement | A service description shall describe a single service. |
Rationale | The readability of any service description is improved by keeping it focussed on one service. |
Verification | Completeness: Not Applicable. Consistency: Not Applicable. Correctness: Verify that one and only one service is described. |
Examples/Notes | Note: The specification covers implemented services, i.e., service instances. A service instance is the service deployed into a running ICT system. Note: The term ‘service’ is used as shorthand for ‘service instance’ in this specification. |
Level of Implementation | Mandatory |
Guidance
No specific guidance is needed for the general case.
When the service is composed of other services, consists of underlying services, such as for an orchestration, the objective of the service description is to describe the composed service as a single service. The goal is to allow the service consumer to make good use of that composed service without the need to understand the underlying complexity. Information on the underlying services may be added, but is not required by the specification.
It is good practice that a service appears as a black-box to its consumers.
The FAQ contains the following questions and answers to help when deciding the service to be described.
- How do I decide on the granularity of a service?
- Each of my service consumers has a dedicated endpoint. Is this described as one service with multiple endpoints or as different services?
Verification Support
Correctness | Check that: [ ] The service description describes one and only one service. |
Examples
Example service descriptions can be found in the European SWIM Registry.
A fictional example is provided as part of this supporting material. See Example service description.