Working towards the next version of the SWIM Supporting Material
Working towards the next version of the SWIM Supporting Material
this is not a requirement
This guidance covers any additional information that is optional and would benefit service consumers.
It mimics the structure of a requirement for a good integration within the guidance material.
Context: The service description spec specifies Mandatory and Recommended information only. Making clear that information may be provided in addition to the prescribed minimum set of elements.
Requirement
Guidance
N/A
Guidance for JSON service description
Schema
The guidance concerns JSON Schema v0.0.3 (see Schema releases).
Guidance
The JSON schema includes the concepts field allowing to cover additional information.
Consider using zero or more instances of the Concept type with information that would improve clarity to the reader.
Concept type
This type covers optional information intended for a good understanding of the service. This may cover design concepts related to the service, logical model, design considerations, or any other information not pertaining to the other fields
attribute | description | guidance | rule |
---|---|---|---|
name | The name of the concept. | Define a short name that makes clear what the description is about. | Mandatory |
description | Description of the concept. | Provide the description. | Mandatory |
Predefined uses of the Concept type
The Concept type covers some predefined uses as well. Each predefined use is related to a requirement, and proposes a value for the "name" field (which would allow automatic processing).
The predefined uses are
requirement | "name" field value |
---|---|
SWIM-SERV-024 Filter capabilities | "Filter capabilities" |
SERV-OVW-008 Geographical extent | "Geographical extent" |
SERV-OVW-017 Sources of information | "Sources of information" |
Example
on going
example to be improved (eg a more specific example)
"serviceGeneralDescription": { ... "concepts": [ { "name": "... short name...", "description": "...optional information..." } ] ...