Working towards the next version of the SWIM Supporting Material
Working towards the next version of the SWIM Supporting Material
Requirement
Title | Examples of code |
Identifier | SWIM-SERV-029 |
Requirement | A service description should include or refer to examples of code exemplifying the implementation of the consuming interface. |
Rationale | Best practice to speed up prototyping. |
Verification | Completeness: Not Applicable. Consistency: If provided, verify that the provided examples correspond to the described service. Correctness: Not Applicable. |
Examples/Notes | Examples include source code in a given programming language, input and output messages. |
Level of Implementation | Recommended |
Guidance
No guidance provided.
Guidance for JSON service description
Schema
The guidance concerns JSON Schema v0.0.3 (see Schema releases).
Guidance
Two cases must be distinguished depending on whether code example is being provided or not.
Case 1 - Code example is provided
Within "serviceDocument" field (itself within "serviceDescriptionReferences" field) create one or more instances of Document with type CODE_EXAMPLE.
See Guidance on serviceDocument on how to fill in documents.
message example
Use document type CODE_EXAMPLE even for message examples. Usage of document type "MESSAGE_EXAMPLE is deprecated.
Case 2 - No code example is provided
Nothing to be mentioned in the JSON service description
Example
"serviceDocument": [ { "documentType": "CODE_EXAMPLE" "title": "Example of messages", "version": "1.0", "description": "A set of message examples", "reference": "public:/2019-09/MessageExamples.txt", }, ... ]
A complete JSON example is available in page JSON example - Donlon TOBT Setting service description.