SWIM Supporting Material

SWIM-SERV-260 Service interface protocols and data format

Owned by WILSON Scott
Last updated: 2024 Jun 10
Page Table of Content

Requirement

Title

Service interface protocols and data format

Identifier

SWIM-SERV-260

Requirement

A service description shall include or refer to information about:

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

Rationale

Makes explicit within the service description what the protocols are.

Verification

Completeness: Verify that all relevant protocols and versions are listed; verify that the information is provided for each provider side and consumer side interface.

Consistency: Verify that the protocols are consistent with the selected interface binding.

Correctness: Not Applicable.

Examples/Notes

Note: The list of supported protocols are the ones corresponding to the selected interface binding. The supported versions of the protocols need to be declared. E.g. version of the Transport Level Security (TLS).

Note: Data format examples include XML and JSON.

Level of Implementation

Mandatory

Guidance

Service Metadata Schema Guidance

The service metadata schema allows flexibility when satisfying this requirement.

  • The service interface protocols are captured as text in the "description" field. This flexible approach was adopted as, in reality, the service interface protocols come in many different forms and a more precise structure in the schema would prove to be too limiting.
  • The data format is captured for each message. This allows a service to provide data in different formats according to the given "schema".

Verification Support

Completeness

Check that:

[  ] The service description includes or refers to information about the service interface protocols (including name and version) for each provider side and consumer side interface.

[  ] The service description includes or refers to information about the data format to be used for each provider side and consumer side interface.

Consistency

Check that:

[  ] The protocols are consistent with the selected interface binding.

Examples

The following example shows the content as a table.

service interface protocols and data format





protocols

XML 1.0 requests and replies embedded into SOAP 1.2 messages, themselves embedded into HTTP/1.1 requests and responses. Operation names are associated to SOAP requests. The interface does not use compression or message transmission optimization mechanism (MTOM). The following cipher suites are allowed in accordance with ECRYPT-CSA recommendations https://www.ecrypt.eu.org/csa/documents/D5.4-FinalAlgKeySizeProt.pdf: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384.

data format

This is captured in the service messages section. See SWIM-SERV-280 Service messages.


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

Example of SWIM-SERV-260 using Service Metadata Schema
"serviceInterface": [{
 "serviceInterfaceBinding": {
  ...
  "description": "XML 1.0 requests and replies embedded into SOAP 1.2 messages, themselves embedded into HTTP/1.1 requests and responses. Operation names are associated to SOAP requests. The interface does not use compression or message transmission optimization mechanism (MTOM). The following cipher suites are allowed in accordance with ECRYPT-CSA recommendations https://www.ecrypt.eu.org/csa/documents/D5.4-FinalAlgKeySizeProt.pdf: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384."
 }
"messages": [{
  ...
  "schema": {
   "url": "https://donlon.eu/schema/1.0.0/tobt/donlon-schema.xsd"
  }
 }
 }]
}]


Complete examples are available at Example service description.

Status: Living Material