Requirement

Title

Service identification

Identifier

SWIM-SERV-006

Requirement

A service description shall include:

  • the name of the service; and
  • the version of the service.

Rationale

This requirement makes clear what the subject of the service description is. It supports the identification and citation 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:

  • include the operational concept supported or the information being exchanged;
  • be a maximum of five words in length;
  • be represented using UpperCamelCase, and not use snake_case; and
  • not end with the ‘service’ suffix.

Level of Implementation

Mandatory


Guidance

Examples

See the Service Identification 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).

		"informationService":
		{
			"description" : "the description of an information service [SWIM-SERV-001]",
			"$ref" :  "#/definitions/InformationService"
		}

		"InformationService" : 
		{
			"description" : "A type of service that provides an ATM information sharing capability.",
			"type": "object",
			"additionalProperties": false,
			"required": ["descriptionInformation", "name", "version", "serviceAbstract", "serviceProvision", "serviceCategorisation", "serviceGeneralDescription", "serviceInformationDescription", "serviceTechnicalDescription", "serviceDescriptionReferences", "serviceInterface"],
			"properties":
			
				"name":
				{
					"description" : "A piece of identifying information that gives stakeholders a way to reference or identify a service. [SWIM-SERV-006]",
					"type" : "string",
					"minLength":1
				},
				"version":
				{
					"description" : "The version of the information service. [SWIM-SERV-006]",
					"type" : "string",
					"minLength":1
				},
		
			}
		}

Rules expressed for the cases as defined in Registry URD.

caserules
COMPLIANTMandatory
CANDIDATEsame
DEFINITIONsame

Guidance

Within field informationService, fill in the following attributes


attributetypedescriptionguidancerule
namestringA piece of identifying information that gives stakeholders a way to reference or identify a service.

Provide the name of the service.

Include the service name only: avoid suffixing with " service".

Mandatory
versionstringThe version of the information service.

Provide the version of the 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.

Rationale: enables consumers to distinguish between releases of the service.

Mandatory

Example

"informationService": {
		
		"name": "TargetOffBlockTimeSetting",
		"version": "1.0.0"
		
		}


A complete JSON example is available in page JSON example - Donlon TOBT Setting service description.