A service definition shall define a single service

Note: This concerns the definition of a service that can be implemented by service providers. It is not used to describe a running service - use a service description in that case.

Note: This requirement uses "define" rather than "describe".

• a title by which the service definition is known;
• an edition; and
• a reference date for use in citing the service definition.

Example:

• title: Aeronautical Dataset Request Service Definition
• edition: 0.21
• reference date: 2020-09-21

Example:

• name: Aeronautical Dataset Request

Example:

• The Aeronautical Dataset Request service allows a service consumer to query the available datasets based on a set of filters and to retrieve datasets that match the filter criteria. The content of the datasets are defined by ICAO Annex 15. The service is part of a series of services that support the concept of aeronautical information product digital data set as defined by ICAO Annex 15.

• the name;
• abbreviated name (if applicable); and
• description of the organisation responsible for the service definition.

Note: the service definition provider is the community of interest or standards development organisation that developed the service definition.

Example:

• name: EUROCAE
• description: ​EUROCAE is the European leader in the development of worldwide recognised industry standards for aviation.

A service definition may include information about the expected geographical coverage of the exchanged information service payload.

Note: the information is intended to help potential service providers understand the service.

Example:

• The service is expected to provide information for a specific FIR or set of FIRs.

Example:

• This service shall provide information for the globe.

A service definition should include information about the typical service provider type and typical service consumer(s) type.

Note: the list service provider and consumer types is intended to help potential service providers understand the service. The list is not prohibitive. 

Note: service descriptions that describe running services can have a different list.

Example:

• typical service provider: 
  • AERONAUTICAL_INFORMATION_SERVICE_PROVIDER
• typical service consumer: 
  • AERONAUTICAL_INFORMATION_SERVICE_PROVIDER
  • AIR_TRAFFIC_SERVICE_PROVIDER
  • CIVIL_AIRSPACE_USER
  • MILITARY_AIRSPACE_USER
  • CIVIL_AIR_NAVIGATION_SERVICE_PROVIDER
  • MILITARY_AIR_NAVIGATION_SERVICE_PROVIDER
  • NETWORK_MANAGER
  • PROVIDER_OF_DATA_SERVICES
  • REGULATED_METEOROLOGICAL_SERVICE_PROVIDER

Example:

• information exchange area:
  • AERONAUTICAL_INFORMATION_EXCHANGE 
    • (See: AERONAUTICAL_INFORMATION_EXCHANGE) 

Example:

• business activity:
  • INFORMATION_MANAGEMENT
    • (See: INFORMATION_MANAGEMENT)

• a reference to the service standard to which the service adheres;
• a statement on any implemented options of the service standard; and
• a statement on any deviation from or addition to the service standard.

Example:

• The service uses the ICAO Digital Data Set Service Definition.

A service definition shall include or refer to information about:

• the operational needs used in the development of the service; and/or
• the capabilities offered by the service.

Example:

• Support the discovery and retrieval of the aeronautical digital data sets as defined by ICAO Annex 15:
  • AIP data set;
  • Obstacle data set;
  • Terrain data set;
  • Airport mapping data set;
  • Instrument flight procedure data set

A service definition shall include or refer to information about:

• the functions expected to be offered by the service in support of its capabilities; and
• their expected real world effects.

Example:

• name: Dataset series query
• description: Allow a service consumer to query the lists of dataset series matching a series of criteria including type, geographical scope, title
• real-world effect: the list of matching dataset series objects is returned

• legal constraints;
• service policies; and
• service consumption constraints.

Example:

• service policy: The service should be free at the point of access.

Example:

• The service shall implement authentication mechanisms to ensure access is limited to authorised users.

• performance;
• reliability; and
• security.

Example:

• availability: 99.95 % outside the planned outages Schedule of planned outages

A service definition shall include or refer to information about the expected minimum quality of the data to be provided by the service.

Note: The items used to describe quality of data vary between information domains. They may include, for example, accuracy, resolution and precision.

Example:

• The data must meet the data quality requirements outlined in the PANS-AIM Data Catalogue. 

A service definition should include information about the expected types of sources of the information provided.

Example:

• regulated meteorological provider

Example: 

• AIR_TRAFFIC_SERVICE_PROVIDER

Example: 

• The service was prototyped in 2021. The service operations and information definition were tested. However, the quality of service was not tested.

Example: 

• SYNCHRONOUS_REQUEST_RESPONSE

A service definition shall include or refer to information about the expected typical behaviour of the service.

Note: The requirement covers the minimum content. Handling of unexpected behaviour is possible to define.

Note: A diagram showing how the operations support the typical behaviour can be provided. This can be made available in the model view (SWIM-DEFN-330).

Example:

• A typical sequence is:
  • (1) The service consumer requests dataset series based on a number of selection criteria, and receives back a list with zero, one or more dataset series objects.
  • (2) The service consumer analyses that list to identify the dataset series he is interested in.
  • (3) The service consumer requests datasets from the selected dataset series, possibly supplying additional selection criteria, and receives back a list of zero, one or more datasets.
  • (4) The service consumer analyses that list to identify the dataset(s) he is interested in.
  • (5) For each dataset of interest
    • (5a) The service consumer requests the file information of the selected dataset, and receives back a list of one or more file objects.
    • (5b) For each file object, the service consumer retrieves the file, and receives back the file content.

Example:

• A service monitoring mechanism is expected to be made available to service consumers.

• the name of the service interface;
• a textual description of the service interface including its purpose;
• an indication that the interface is a provider side interface or a consumer side interface

Note: If no service interfaces are expected, the service implemented can group operations and messages as fit.

Example:

• name: SearchAndRetrieve
• description: The interface allows querying metadata and retrieving files.
• interface provision side: PROVIDER_SIDE_INTERFACE

A service definition shall include information about the selected SWIM TI Profile and its version for each service interface.

Note: This can be captured at service level if all of the service interfaces will use the same SWIM TI Profile.

Example:

• profile: SWIM_TI_YP_1_0
  

A service definition may include for each service interface:

• a reference to a service interface binding as specified in the selected SWIM TI Profile;
• a reference to a network interface binding as specified in the selected SWIM TI Profile; and
• references to additionally supported requirements as specified in the selected SWIM TI Profile.

Example:

• service interface binding:  WS_LIGHT
• network interface binding: IPV4_UNICAST
• additional support: SWIM-TIYP-0092, SWIM-TIYP-0098

A service definition may include or refer to information about:

• the service interface protocols (including name and version); and
• data format to be used.

Note: Protocols are normally linked to the service interface binding. The information provided here must be consistent with what is selected in SWIM-DEFN-255.

Note: If a data format is listed, it must be consistent with what is allowed by the bindings mentioned in SWIM-DEFN-255.

Example:

• name: TLS 1.2
• data format: XML

• the name of the service operation; and
• a description of the intent and the results of the service operation.

Example:

• name: queryDatasets
• description: The operation accepts criteria about datasets and returns a list with the metadata about the corresponding datasets.

A service definition shall include or refer to information about the expected messages that are exchanged by the service including input, output and error messages.

Note: there needs to be at least one message. 

Example:

• in: QueryDatasetsRequest 
• out: QueryDatasetsReply

• the name of the element;
• the definition of the element;
• the data type used by the element if applicable; and
• the semantic correspondence of the element with the AIRM.

Note: Service definitions can use an information exchange schema that is uses the data format selected in SWIM-DEFN-260.

Example:

• concept:
  • name: Aerodrome
  • definition: A defined area on land or water (including any buildings, installations and equipment) intended to be used either wholly or in part for the arrival, departure and surface movement of aircraft.
  • semantic correspondence: urn:aero:airm:1.0.0:LogicalModel:Subjects:BaseInfrastructure:AerodromeInfrastructure:Aerodrome

Example:

• reference: see the Model View provided.

• the cardinality applicable to the element, including whether the element is optional, conditional or mandatory in the exchange;
• constraints applicable to the element, such as:
  • value ranges;
  • special values;
  • character set restrictions; and
• the structure and relevant relationships between the elements.

Example:

• reference: see the Model View provided.

If information service payload filtering is expected, a service definition shall or refer to information about the filter encoding.

Example:

• The service consumer should be able to filter information feed based on time and geospatial criteria.

If the service interface binding specifies the use of machine-readable formats, a service definition should include or refer to a service interface definition in a machine-readable format using a standard service definition formalism/language.

Note:  'include' means to embed the machine-readable format into the service definition. It is still a separate artefact.

Example:

• title: Interface WSDL
• description: Machine processable description of the service interface
• reference: public:/2019-09/TOBT_Interface.wsdl

• include or refer to a model view, expressed using a formal and standardised notation, that formalises the representation of the business logic of its service interfaces, service operations, service behaviour and exchanged information; and
• declare the notation used to express the model view.

Example:

• title: The model view of the service
• description: The model view of the service
• reference: public:/2019-09/TOBT_Interface_ModelView.uml

Example:

• abbreviation:
  • code: ATM
  • term: Air Traffic Management