Working towards the next version of the SWIM Supporting Material

Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Table of Contents

Requirement

Panel
borderColorlightgrey
bgColorwhitesmoke
borderStyledashed

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:

function

real world effect

Retrieve a list of flights

(Network Information sharing)

Retrieve information of a single flight

(Network Information sharing)

Provide Departure Planning Information (DPI)

NM systems updated with the information; NM systems publish the resulting flight update

Level of Implementation

Mandatory


Guidance

Examples

See the Service Functionality section within the Donlon TOBT Setting Service Description.

Guidance for JSON service description 

Excerpt

Include Page
SCOI:with JSON guidance
SCOI:with JSON guidance

Schema

The guidance concerns JSON Schema v0.0.3 (see Schema releases).

Expand
titleSchema excerpt [+]
Code Block
languagejs
		"ServiceGeneralDescription" : 
		{
			"description" : "Description of the service in terms of what it provides, the purpose and under which conditions and quality levels the service is provided.",
			"type": "object",
			"additionalProperties": false,
			"required": ["operationalNeed", "functionality", "qualityOfService", "accessAndUseCondition", "validation"],
			"properties":
			{

 				"functionality":
				{
					"description" : "A type of activity describing the functionality of a service. [SWIM-SERV-012]",
					"type" : "array",
					"items" : { "$ref":"#/definitions/Functionality" },
					"minItems": 1
				},

			}
		},


		"Functionality" : 
		{
			"description" : "A type of activity describing the functionality of a service.",
			"type": "object",
			"additionalProperties": false,
			"required": ["name", "description", "realWorldEffect"],
			"properties":
			{
				"name":
				{
					"description" : "The name of the service function.",
					"type" : "string",
					"minLength":1
				},
				"description":
				{
					"description" : "Description of the service function. [SWIM-SERV-012]",
					"type" : "string",
					"minLength":1
				},
				"realWorldEffect":
				{
					"description" : "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]",
					"type" : "string",
					"minLength":1
				}
			}
		},
Expand
titleRules [+]

Rules expressed for the cases as defined in Registry URD.

caserules
COMPLIANTmandatory
CANDIDATEsame
DEFINITIONsame

Guidance

Express the functionality offered by the service as a list of service functions.Rationale:

Within field functionality (itself within field serviceGeneralDescription) list one or more occurrences of type Functionality. 


Info
titlebusiness 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.

Within field functionality (itself within field serviceGeneralDescription) list one or more occurrences of type Functionality. 

The service operations provide 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 namedescriptiontypeguidancerule
nameThe name of the service function.stringProvide a short name for the service functionMandatory
descriptionDescription 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
realWorldEffectAn 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

Code Block
languagejs
        "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.