Working towards the next version of the SWIM Supporting Material

Page tree

Working towards the next version of the SWIM Supporting Material

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 3 Current »

Frequently Asked Questions about the implementation of the SWIM Service Description specification. Including direct link to the supporting material when applicable.



How does a service description relate to a service level agreement?

See Formal Arrangements - Service Level Agreements.

The conformance checking for our service was by self-assessment. Is this correct? Is there a role for governance? What about supervisory authorities?

The conformance to the specifications is done by self-assessment. National supervisory authorities may be involved. EUROCONTROL is not involved.

Supporting Material

How do I show compliance with Common Project 1 (CP1)?

The SESAR Deployment Programme (SDP) talks about the need for “concrete requirements that the service needs to fulfill to comply with”. The SWIM requirements are then detailed in a dedicated section (p130). This section is a good start for a compliance checklist but remember that the national supervisory authorities may have different requirements. It states:  

SWIM requirements (from SDP)

This section consolidates what is expected as tangible outcomes when implementing a SWIM service.  Service Providers are required to deploy information services that:

  • Enable the exchange of information in alignment with the intended scope, e.g. Scope as identified in CP1 and further elaborated in the Deployment Programme
  • Use communication protocols and implement infrastructure requirements as defined in EUROCONTROL SWIM TI YP specification.
  • In case confidentiality, integrity or authenticity is required, use digital certificates
  • Are described based on
    • EUROCONTROL Service Description specification
    • EUROCONTROL Information Definition specification
  • Conform to published service definitions (if available and applicable)
    • The service provider identifies whether applicable service definitions are publicised in the SWIM Registry and adapts its implementation to conform to this if needed.
  • Are publicised in the SWIM Service Registry.

 Service Consumers are required to consume from information services that:

  • Enable the exchange of information in alignment with the intended scope
  • e.g. Scope as identified in CP1 and further elaborated in the following sections of Deployment Programme

Related links

How do I record the use of GRIB2 in my service?

This best practice covers how to detail the use of e.g. GRIB2 in the service description.

SWIM-SERV-260 Service interface protocols and data format


The selection of protocol and data format for this requirement must be consistent with the interface service binding selected in SWIM-SERV-250 SWIM TI Profile and interface bindings.

The selection is found in the TIYP Specification (see diagrams below).

  • WS-Light
    • no specific data format is required by the TIYP specification
  • WS-SOAP
    • the service has to support XML (SWIM-TIYP-0029)
      • this applies to the messages that are exchanged by the service.
      • it is possible for the XML formatted message to embed a file.
      • SWIM-TIYP-0033 gives the content that can be embedded (e.g., as multipart files) based around MIME type.



Example

The document below contains recommendations concerning GRIB2 and WCS, (e.g. Content Type Headers). It explains the mechanism to exchange multipart type of messages for the HTTP extensions.

Best practice

  • Details on GRIB2 are captured for the data format requirement. In the service metadata schema use the exchangeSchema field for this.
  • If using WS-SOAP
    • In the service metadata schema use interfaceBindingDescription field to explain GRIB2 is embedded in the XML messages.


Service metadata example
"serviceInformationDescription": {
...
 "exchangeSchema": [
  {
   "name": "GRIB2",
   "schemaLanguage": "coverage",
   "reference": "reference to GRIB2 standard."
  }
 ]
...
}
Service metadata example
"serviceInterface": [
 {
  "interfaceBindingDescription": "XML requests and replies. GRIB2 is embedded (as zipped files) into the reply messages.",
 }


  • in contrast to the above, here is what to do if using IWXXM...
Service metadata example
"serviceInformationDescription": {
...
 "exchangeSchema": [
  {
   "name": "IWXXM 3.0",
   "schemaLanguage": "XML",
   "reference": "https://schemas.wmo.int/iwxxm/3.0/"
  }
 ]
...
}

Options for the schemaLanguage  are:

  • coverage. The message contains gridded/raster data. This is used for e.g. GRIB2 and netCDF files.
  • image/map. The message contains a rendered, geo-located image/map. This is used for e.g. JPEG, PNG and SVG files.
  • XML. The message contains non-gridded data. This is used for e.g. IWXXM. 


SWIM-SERV-290 Information definition - minimum


The requirement expects the content of the service payload to be defined. It is here that the content of the GRIB2 file e.g. turbulence should be defined. However, GRIB2 is a standard owned and defined for the MET domain, not the Aviation MET domain. Therefore it is out of scope of the AIRM. 

Best practice

  • Define the essential aspect of the information being exchanged e.g. turbulence. In the service metadata schema use the informationDefinition field for this,
  • Ensure this essential aspect if defined in accordance with the AIRM.


Service metadata example
"informationDefinition": [
 {
  "name": "Turbulence",
  "description": "Atmospheric flow regime characterized by chaotic and stochastic property changes. This includes low momentum diffusion, high momentum convection, and rapid variation of pressure and velocity in space and time.",
  "semanticCorrespondence": "urn:aero:airm:1.0.0:LogicalModel:Subjects:Meteorology:Turbulence"
 }
],





How do I define the list of topics for use in AMQP 1.0?

AMQP 1.0 technically has no subscription function (unlike 0.9). Subscription is handled by a broker.

The need for harmonisation/guidance on topic trees is not unique to AMQP 1.0.

The role of topics is discussed in the TIYP supporting material. See, e.g., the "Subject-based Filtering" section in https://reference.swim.aero/technical-infrastructure/guidance-for-pub-sub-push-implementation.html that discusses topic enumerations and topic trees. The getTopics operation allows a service consumer to request the list of topics that are available to use in the subscription.

The topics themselves are URIs and should be based on the data that is exchanged. The need for semantic interoperability applies to the topic names. Therefore, it a best practice to use terms coming from a common semantic reference such as the a stardardised information exchange model, the AIRM and/or the list of service categories.

An example, using terms from the AIRM and the format used in the TIYP supporting material:

  • /meteorology/precipitation
  • /meteorology/precipitation/LFPG


It is also best to avoid business and service logic in the topic tree such as the way in which the data is served. There is also no need to prefix the items in the topic tree with e.g. "topic/"

Domains may agree their own topic trees. For example, work on topic trees is occurring within the MET community. See https://wmo-teams.atlassian.net/wiki/spaces/WIS2/pages/167313674/WIS+2.0+Demonstration+Projects+Workshop.  

How do I decide on the granularity of a service?

It is difficult to provide an exact answer to this question because there are many factors that affect the granularity of the service.

Service granularity is related to the design principle of service composability which defines services in such a way that they can be used in a service composition. A service composition is an aggregation of services where many smaller (i.e. fine grained) services (the composition members) are combined together in a larger (coarse grained) service. Typically a composition member provides functionality to the other services in the service composition. An example to think of as service composition is a service that mashes up data from various domains to create integrated picture (e.g. combining aeronautical information with flight data).

The functional scope also affects the granularity of the service. It is based on the operational needs of the service consumer. The service should be meaningful in the sense that it solves a whole problem for users and it is important to understand what that problem is e.g. is it to see all of the meteorological weather products or simply METARs.

See the Service Orientation Process knowledge article - in particular, the Identify and Design steps are useful in understanding users and their needs.


The information exposed also affects the granularity. For example, the service may have operations to allow a consumer to get all messages, get an individual message, get a property of a message or a combination of these. The decision here is also driven by operational needs and the information exchange requirements. Likewise, the format of the information can be a driver - is it preferable to have one service that provides information in many formats (e.g. IWXXM and GRIB2) or to have each format as a separate service. However, in general, a new format and/or technical protocol is introduced in a new interface within the existing service.

The Interoperability Architecture, in particular, the organisational view is most relevant here.


The decision also depends on where the service sit in the overall service oriented architecture. For example, a coarse-grained service may be exposed to a set of external consumers closer to an application/business need while microservices are exposed more transversely but also more at the heart of common functionality for all, hence also the practices around microservices.

In Europe, some services that implement information exchanges are regulated, in the sense that they are listed in the EU Regulation - Common Project 1 and in the SESAR Deployment Programme. These may act as a guide in deciding the granularity of a new service. On the other hand, the list may act as input to a wider service orientation activity.

Each of my service consumers has a dedicated endpoint. Is this described as one service with multiple endpoints or as different services?

This situation allows each service consumer to have the information customised to their needs. However, as the operational need and functionality of the service remains consistent, it is a best practice to deal with this as a single service.

The Service Metadata Schema for service descriptions makes the definition of at least an endpoint mandatory. Therefore, it is not possible to simply ignore the endpoint field. However, the schema does allow users to define multiple endpoints and you can also use parameterized URLs (to illustrate: https://www.domain.com/url?variable=value&variable=value). The use of parameterized URLs is very common and can be a sensible solution to the problem described while fitting inside the current schema restrictions. The description of the endpoint can then be used to say that the parameters will be assigned to the consumer when a formal arrangement (such as a service level agreement) is agreed.

How do I document the HTTP error codes in my service description?

My service relies on the standard HTTP error codes. Is there a need to document them in the service description?

The Examples/Notes section of requirement SWIM-SERV-220 Service behaviour explains that error messages and error handling in general can be included in a model view (as part of SWIM-SERV-330 Model view). They are modelled as part of the detailed service behaviour.

However, it is possible to add an entry in the service behaviour section of a service description. For example:

exception handling

The following HTTP status codes, with the meaning explained in the context of the service, are used by the service operations:

400 Bad Request: Indicated for malformed requests on the part of the client.

401 Unauthorized: Indicated for authentication errors (e.g. the authentication is not provided, the credentials used do not exists, the authentication mechanism used is not valid…).

403 Forbidden: Indicated for authorization errors (e.g. the authenticated credentials are not allowed to perform this operation on the resource).

404 Not Found: The requested resource cannot be found (e.g. the <subscription_id> does not exist).

405 Method Not Allowed: The HTTP method used is not supported by the resource.

500 Internal Server Error: Catch-all error for unexpected internal errors during the processing of the request.

Other error messages are documented in SWIM-SERV-280 Service messages.




  • No labels