Working towards the next version of the SWIM Supporting Material
Working towards the next version of the SWIM Supporting Material
Requirement
Title | Machine-readable service interface definition |
Identifier | SWIM-SERV-020 |
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:
Note: AMQP does not mandate a specific machine-readable format. Note: REST may use WSDL 2.0 or WADL. However, WADL is not standardised. |
Level of Implementation | Mandatory Conditional |
Guidance
No guidance provided.
Guidance for JSON service description
Schema
The guidance concerns JSON Schema v0.0.3 (see Schema releases).
Guidance
Within "serviceDocument" field (itself within "serviceDescriptionReferences" field) create zero or more instances of Document with type MACHINE_READABLE_SERVICE_DESCRIPTION.
See Guidance on serviceDocument on how to fill in documents.
Example
"serviceDocument": [ ... { "documentType": "MACHINE_READABLE_SERVICE_DESCRIPTION", "title": "TOBT Setting Schema", "version": "1.0", "description": "JSON Schema describing the structure of information", "reference": "public:/2019-09/TOBTSetting_JSON.txt" }, { "documentType": "MACHINE_READABLE_SERVICE_DESCRIPTION", "title": "Interface WSDL", "version": "", "description": "Machine processable description of the service interface", "reference": "public:/2019-09/TOBT_Interface.wsdl" }, ... ]
A complete JSON example is available in page JSON example - Donlon TOBT Setting service description.