Page Table of Content

Requirement

Title	Service identification
Identifier	SWIM-SERV-040
Requirement	A service description shall include: the name of the service; and the version of the service.
Rationale	This requirement ensures that a specific version of a service from a service provider can be uniquely identified. It makes clear what the subject of the service description is. It enables the identification and referencing of the service being described.
Verification	Completeness: Verify that the 2 elements are included Consistency: Not Applicable. Correctness: Not Applicable.
Examples/Notes	Example service identifications: “TargetOffBlockTimeSetting service, version 1.3.0”; “FlightManagement service, version 20.0”. Note: To improve readability across service descriptions, it is best practice to apply following conventions for a service name: the name provides an indication of the purpose of the information service; be a maximum of five words in length; be represented using UpperCamelCase, and not use snake_case; and not end with the ‘service’ suffix. Note: It is a best practice for the service version to be provided in numerical format (n.n[.n]).
Level of Implementation	Mandatory

Guidance

Name of the service

The name of the service is a piece of identifying information that gives stakeholders a way to reference or identify a service. It is best to include the service name only; avoid suffixing with "service".

The version is always provided regardless of whether or not there are multiple versions of a service. Each version of a service shall have its own completed description. This enables service consumers to distinguish between releases of the service.

Versioning

The Examples/Notes to the requirement include:

Note: It is a best practice for the service version to be provided in numerical format (n.n[.n]).

This is in line with the text provided in the Information service version field of the ICAO information service overview (Information Service Overview Handbook v1.1). However, no other advice on versioning is given in the specification.

In order to support easier management of services and to support automation, the following best practice is given, expanding upon the best practice currently found in the specification.

Best Practice

It is a best practice for the service version to be provided according to the Semantic Versioning 2.0.0 (https://semver.org/) format.

It is possible to meet this best practice by interpreting the text currently found in the specification as requiring the numerical format to be (n.n.n) rather than leaving the last number as optional.

Future versions of the EUROCONTROL Specification for SWIM Service Description may be updated to reflect the new best practice.

Verification Support

Completeness

Check that:

[ ] The service description includes a name for the service.

[ ] The service description includes a version for the service.

Examples

The following example shows the content as a table.

service identification	service name	TargetOffBlockTimeSetting
service identification	version	1.3.0

The following example shows an extract of the content of a JSON file that conforms to the Service Metadata Schema

Example of SWIM-SERV-040 using Service Metadata Schema

"serviceIdentification": {
 "name": "TargetOffBlockTimeSetting",
 "version": "1.3.0"
}

Complete examples are available at Example service description.