Working towards the next version of the SWIM Supporting Material
Working towards the next version of the SWIM Supporting Material
Requirement
Title | Service behaviour |
Identifier | SWIM-SERV-025 |
Requirement | A service description shall include information on the behaviour of the service including:
|
Rationale | This requirement facilitates the understanding of the service behaviour, including the sequencing of service operations to support operational processes, and the error handling. |
Verification | Completeness: Verify that the behaviour information is included and covers the errors handling as well. Consistency: Verify that the names of the interfaces, service operations and exchanged information are consistent with the interface definitions. Correctness: Not Applicable. |
Examples/Notes | Examples of behaviour specification:
Note: The service behaviour can be captured in formal modelling notations such as a Unified Modeling Language (UML) sequence diagram, and/or expressed as textual description in plain language. |
Level of Implementation | Mandatory |
Guidance
Examples
See the Service behaviour section within the Donlon TOBT Setting Service Description.
Guidance for JSON service description
tentative JSON Guidance
Guidance for JSON service descriptions integrated within the SWIM Service Description Handbook.
Schema
The guidance concerns JSON Schema v0.0.3 (see Schema releases).
Guidance
In JSON the service behaviour is expressed per service interface.
This may be complemented by a service SERVICE_BEHAVIOUR_DESCRIPTION document.
tip
The service behaviour can be captured in formal modelling notations such as a Unified Modeling Language (UML) sequence diagram, and/or expressed as textual description in plain language.
In the latter case, whether for a model file or for a document with diagrams, use a SERVICE_BEHAVIOUR_DESCRIPTION document.
Per service interface (mandatory)
It is mandatory to provide one or more service behaviour(s) for each interface.
Notes:
- Service behaviour often concerns closely related operations in the same interface.
- When service behaviour relate operations from different interfaces, feel free to describe it in one of the concerned interfaces.
- When service behaviour is made available in a document, make this clear in the behaviour.description of each interface
attribute name | description | type | guidance | rule |
---|---|---|---|---|
name | The name of the service behaviour. | string | Provide a short name for the behaviour | Mandatory |
description | The description of the service behaviour. | string | Describe the behaviour as
And / or make reference to a SERVICE_BEHAVIOUR_DESCRIPTION document. | Mandatory |
Service behaviour document (optional)
Service behaviour may be provided as a document of type SERVICE_BEHAVIOUR_DESCRIPTION.
See Guidance on serviceDocument on how to fill in documents.
JSON example
"serviceInterface": [ { ... "behaviour": [ { "name": "nominal behaviour", "description": "Each operation of the interface can be called independently.\r\nThe following diagram illustrates the interaction between the service consumer and the service" } ] ... } ]
"serviceInterface": [ { ... "behaviour": [ { "name": "behaviour document", "description": "The service behaviour is fully described in the SERVICE_BEHAVIOUR_DESCRIPTION document" } ], ... } ] "serviceDocument": [ { "documentType": "SERVICE_BEHAVIOUR_DESCRIPTION " "title": "Service Behaviour", "version": "1.0", "description": "", "reference": "... ...", }, ... ]
A complete JSON example is available in page JSON example - Donlon TOBT Setting service description.