SWIM Supporting Material

SWIM-SERV-320 Machine-readable service interface definition

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

Requirement

Title

Machine-readable service interface definition

Identifier

SWIM-SERV-320

Requirement

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

Rationale

Enables consumer software components to be created.

Verification

Completeness: If the service interface binding supports it, verify that the required elements are included.

Consistency: Verify that provided elements are consistent with the selected binding.

Correctness: Not Applicable.

Examples/Notes

Example machine-readable descriptions:

  • service descriptions:
    • WSDL (e.g. if a Web Service binding using SOAP is selected);
  • message descriptions:
    • XSD;
    • Schematron Rules.

Note: AMQP does not mandate a specific machine-readable format.

Note: REST may use OpenAPI, WSDL 2.0 or WADL.

Level of Implementation

Mandatory (Conditional)

Guidance

Verification Support

Completeness

Check that:

[  ] The service description includes or refers to a service interface definition in a machine-readable format if the service interface binding supports it.
Consistency

Check that:

[  ] The provided elements are consistent with the selected binding.

Examples

The following example shows the content as a table.

machine-readable service interface definition

public:/2019-09/TOBT_Interface.wsdl



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

Example of SWIM-SERV-320 using Service Metadata Schema
"references": {
 "serviceDocument": [{
  "documentType": "MACHINE_READABLE_SERVICE_DESCRIPTION",
  "title": "Interface WSDL",
  "version": "1.0",
  "description": "Machine processable description of the service interface",
  "reference": {
   "url": "public:/2019-09/TOBT_Interface.wsdl"
  }
 }]
}

Complete examples are available at Example service description.


Status: Living Material