Working towards the next version of the SWIM Supporting Material
Working towards the next version of the SWIM Supporting Material
Requirement
Title | Service functionality | ||||||||
Identifier | SWIM-SERV-012 | ||||||||
Requirement | A service description shall describe the functionality of the service as a list of functions and their associated real world effects. | ||||||||
Rationale | The functions provide business and operational experts with a business view of the interactions with the service, without having to look at the interface details. | ||||||||
Verification | Completeness: Verify that the elements are included. Consistency: Verify that the functions and real world effects are consistent with the operational needs. Correctness: Not Applicable. | ||||||||
Examples/Notes | Note: A function is a type of activity describing the functionality of a service. Every function usually (but not always) can be mapped to service operations defined as a part of the service’s interface; i.e., functions provide a “business view” and service operations provide a “technical view” of a particular service activity. Note: A real world effect is an ultimate purpose associated with the interaction with the service. It may be the response to a request for information or the change in the state of some entities shared between the participants in the interaction. Example functions and real world effects:
| ||||||||
Level of Implementation | Mandatory |
Guidance
Examples
See the Service Functionality section within the Donlon TOBT Setting Service Description.
Guidance for JSON service description
Schema
The guidance concerns JSON Schema v0.0.3 (see Schema releases).
Guidance
Express the functionality offered by the service as a list of service functions.
Within field functionality (itself within field serviceGeneralDescription) list one or more occurrences of type Functionality.
business view
The functions provide business and operational experts with a business view of the interactions with the service, without having to look at the interface details.
The service operations provide with a technical view of the interactions (see SWIM-SERV-021 Service operations)
Functionality - Mandatory
Note: A function is a type of activity describing the functionality of a service. Every function usually (but not always) can be mapped to service operations defined as a part of the service’s interface; i.e., functions provide a “business view” and service operations provide a “technical view” of a particular service activity.
attribute name | description | type | guidance | rule |
---|---|---|---|---|
name | The name of the service function. | string | Provide a short name for the service function | Mandatory |
description | Description of the service function. | string | Describe the service function. Note: A function is a type of activity describing the functionality of a service. Every function usually (but not always) can be mapped to service operations defined as a part of the service’s interface; i.e., functions provide a “business view” and service operations provide a “technical view” of a particular service activity. | Mandatory |
realWorldEffect | An ultimate purpose associated with the interaction with the service. It may be the response to a request for information or the change in the state of some entities shared between the participants in the interaction. [SWIM-SERV-012] | string | Guidance: describe here the real-world-effect, if any. May be left blank if not realWorldEffect outside the sharing of information. Note: A real world effect is an ultimate purpose associated with the interaction with the service. It may be the response to a request for information or the change in the state of some entities shared between the participants in the interaction. | Mandatory, can be empty. |
Example
"serviceGeneralDescription": { "functionality": [ { "name": "Set TOBT", "description": "Allow the service consumer to set (i.e. define or update) the TOBT value for a specific flight.", "realWorldEffect": "The Target Off-Block Time (TOBT) value is defined" }, { "name": "Delete TOBT", "description": "Allow the service consumer to delete the TOBT value for a specific flight.", "realWorldEffect": "The Target Off-Block Time (TOBT) value is undefined" } ], },
A complete JSON example is available in page JSON example - Donlon TOBT Setting service description.