Working towards the next version of the SWIM Supporting Material
Working towards the next version of the SWIM Supporting Material
UNDER WORK
Usage and requirements
Rationale: A JSON service description does not include all information useful to service consumers. Some information are made available as separate documents. Examples of such documents are the Information Definition and Machine Readable Service Description.
Several case exist:
- Some documents are explicitly linked to requirements they may help to satisfy.
- Some documents are mandatory
- Some requirements have no other information within the JSON service description than the document (in bold below)
Each document has a document type that makes explicit the content of the document and may link to the requirement it helps satisfy (see CodeDocumentType below).
This is all made visible in the table below
requirement | comment | document type |
---|---|---|
SWIM-SERV-013 Access and use conditions | POLICY_DOCUMENT | |
SWIM-SERV-014 Quality of service | QUALITY_OF_SERVICE_DOCUMENT | |
SWIM-SERV-020 Machine-readable interface | No other info in JSON service description | MACHINE_READABLE_SERVICE_DESCRIPTION |
SWIM-SERV-022 Information definition | This document is mandatory | INFORMATION_DEFINITION (AIRM_TRACE when semantic correspondence is separate from information definition) |
SWIM-SERV-025 Service behaviour | SERVICE_BEHAVIOUR_DESCRIPTION | |
SWIM-SERV-026 Model view | No other info in JSON service description | SERVICE_MODEL |
SWIM-SERV-027 Service validation | SERVICE_VALIDATION_REPORT | |
SWIM-SERV-029 Examples of code | No other info in JSON service description | CODE_EXAMPLE |
Other document types exist for documents not related to the service description specification requirements
Guidance for JSON service description
Schema
The guidance concerns JSON Schema v0.0.3 (see Schema releases).
Guidance
Provide at least a document with type INFORMATION_DEFINITION
Within field serviceDocument, itself within field serviceDescriptionReferences, ""), list here one or more documents related to the service description. At the minimum, the Information Definition must be provided.
Document - Mandatory
Description: A piece of written, printed, or electronic matter that provides information or evidence or that serves as an official record.
attribute name | description | type | guidance | rule |
---|---|---|---|---|
documentType | The type of document. | CodeDocumentType | Select the code according to usage described in Code Lists walk-through. | Mandatory |
title | The name by which the document is formally known. | string | Provide the document name. | Mandatory |
version | The current version or revision level of the document. | string | Provide the document version. In absence of a version, consider providing the document reference date. | Mandatory |
description | The description of the document. | string | Optionally provide a description for the document. For a SERVICE_MODEL document (req SWIM-SERV-026 Model view), declare the notation used to express the model view. | Optional |
reference | An external reference at which the document can be retrieved or consulted. | string | Provide an external reference when available. In absence of an external reference, leave empty. Registry may help providing a reference later on. | Optional |
CodeDocumentType - Mandatory
A code describing types of documents.
- Ordered by requirements.
- In bold the requirements that are satisfied by document(s) only.
tip
Select SERVICE_SPECIFICATION for any other kind of document.
value | requirement / usage | guidance | rule |
---|---|---|---|
POLICY_DOCUMENT | SWIM-SERV-013 Access and use conditions | Select this value for any document in relation to access and use conditions | Optional |
QUALITY_OF_SERVICE_DOCUMENT | SWIM-SERV-014 Quality of service | Select this value for any document in relation to quality of service | Optional |
MACHINE_READABLE_SERVICE_DESCRIPTION | SWIM-SERV-020 Machine-readable interface | Select this value for machine readable document | Mandatory Conditional |
INFORMATION_DEFINITION | SWIM-SERV-022 Information definition | Select this value for information definition document At least one INFORMATION_DEFINITION document is required. | Mandatory |
AIRM_TRACE | SWIM-SERV-022 Information definition | Select this value for semantic correspondence document, when separated from the the information definition. | Optional |
SERVICE_BEHAVIOUR_DESCRIPTION | SWIM-SERV-025 Service behaviour | Select this value for service behaviour document (eg with sequence diagrams) | Optional |
SERVICE_MODEL | SWIM-SERV-026 Model view | Select this value for service model file. | Recommended |
SERVICE_VALIDATION_REPORT | SWIM-SERV-027 Service validation | Select this value for service validation report | Optional |
CODE_EXAMPLE | SWIM-SERV-029 Examples of code | Select this value for code examples and/or message examples document. | Recommended |
SERVICE_STANDARD | SWIM specification conformance assessment report (SWIM-REG-0004 Service categorization ) | Select this value for conformance assessment report concerning the SWIM specifications. For service standard reference, do not make a document instance, prefer using field implementedStandard.reference (see guidance in SWIM-SERV-010 Service standard reference). | Optional |
SERVICE_SPECIFICATION | for all other uses | Select this value for any other document. For instance, additional information such as User Manual, Reference Manual, etc. | Optional |
MESSAGE_EXAMPLE | do not use | Do not use this value For message examples use CODE_EXAMPLE | - |
PROTOCOL_SPECIFICATION | do not use | Do not use this value | - |
SERVICE_CERTIFICATION | do not use | Do not use this value For provider certification use field serviceProvision.providerDescription (as explained in SWIM-SERV-008 Service provider). | - |
Example
"serviceDescriptionReferences": { "serviceDocument": [ { "documentType": "INFORMATION_DEFINITION", "title": "TOBT Setting Information Definition", "version": "1.0", "description": "Information Definition for the DONLON TOBT Setting service. Includes Semantic correspondence with traces to the AIRM", "reference": "public:/2019-09/TraceToAIRM.txt" }, { "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" }, { "documentType": "CODE_EXAMPLE", "title": "Example of messages", "description": "A set of message examples", "version": "1.0", "reference": "public:/2019-09/MessageExamples.txt" } ] }
A complete JSON example is available in page JSON example - Donlon TOBT Setting service description.