Working towards the next version of the SWIM Supporting Material

Page tree

Working towards the next version of the SWIM Supporting Material

Skip to end of metadata
Go to start of metadata

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 

requirementcommentdocument 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 descriptionMACHINE_READABLE_SERVICE_DESCRIPTION 
SWIM-SERV-022 Information definitionThis 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 viewNo other info in JSON service descriptionSERVICE_MODEL 
SWIM-SERV-027 Service validation
SERVICE_VALIDATION_REPORT 
SWIM-SERV-029 Examples of codeNo other info in JSON service descriptionCODE_EXAMPLE 

Other document types exist for documents not related to the service description specification requirements

Guidance for JSON service description 

tentative JSON Guidance

Schema

The guidance concerns JSON Schema v0.0.3 (see Schema releases).

 Schema excerpt [+]
		"ServiceDescriptionReferences" : 
		{
			"description" : "References to complementary documents that provide additional details about the service.",
			"type": "object",
			"additionalProperties": false,
			"required": ["implementedStandard"],
			"properties":
			{


				"serviceDocument":
				{
					"description" : "A document that relates to the information service.",
					"type" : "array",
					"items" : { "$ref":"#/definitions/Document" },
					"minItems": 1
				}


			}
		}


		"Document" : 
		{
			"description" : "A piece of written, printed, or electronic matter that provides information or evidence or that serves as an official record.",
			"type": "object",
			"additionalProperties": false,
			
			"properties":
			{
				"documentType":
				{
					"description" : "The type of document.",
					"$ref" : "#/definitions/CodeDocumentType"
				},
				"title":
				{
					"description" : "The name by which the document is formally known. [SWIM-SERV-005;SWIM-SERV-010]",
					"type" : "string"
				},
				"version":
				{
					"description" : "The current version or revision level of the document.",
					"type" : "string"
				},
				"description":
				{
					"description" : "The description of the document.",
					"type" : "string"
				},
				"reference":
				{
					"description" : "An external reference at which the document can be retrieved or consulted.",
					"type" : "string"
				}
			}
		},


 Rules [+]

Rules expressed for the cases as defined in Registry URD.

caserules
COMPLIANTmandatory
CANDIDATEsame
DEFINITIONsame

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 namedescriptiontypeguidancerule
documentTypeThe type of document.CodeDocumentType

Select the code according to usage described in Code Lists walk-through.

Mandatory
titleThe name by which the document is formally known.stringProvide the document name.Mandatory
versionThe 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
descriptionThe 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
referenceAn 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.

valuerequirement / usageguidancerule

POLICY_DOCUMENT

SWIM-SERV-013 Access and use conditionsSelect this value for any document in relation to access and use conditionsOptional

QUALITY_OF_SERVICE_DOCUMENT 

SWIM-SERV-014 Quality of serviceSelect this value for any document in relation to quality of serviceOptional

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 behaviourSelect 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 validationSelect this value for service validation reportOptional

CODE_EXAMPLE 

SWIM-SERV-029 Examples of codeSelect 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.


  • No labels