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


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:

  • service descriptions:
    • WSDL (e.g. if a Web Service binding using SOAP is selected);
  • message descriptions:
    • XSD;
    • Schematron Rules.

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 

tentative JSON Guidance

Schema

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

 Schema excerpt [+]
			"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 Conditional
CANDIDATEOptional
DEFINITIONOptional

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.

  • No labels