Working towards the next version of the SWIM Supporting Material

Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Table of Contents

Requirement

Panel
borderColorlightgrey
bgColorwhitesmoke
borderStyledashed

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 

Excerpt

Include Page
SCOI:With with JSON guidance
SCOI:With with JSON guidance

Schema

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

Expand
titleSchema excerpt [+]
Code Block
languagejs
			"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"
				}
			}
		}
Expand
titleRules [+]

Rules expressed for the cases as defined in Registry URD.

caserules
COMPLIANToptional
CANDIDATEsame
DEFINITIONsame

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.

Info
titlemessage 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

Code Block
languagejs
titlecase 1 - code example provided
	"serviceDocument": [
                {
                    "documentType": "CODE_EXAMPLE"
                    "title": "Example of messages",
                    "version": "1.0",
                    "description": "A set of message examples",
                    "reference": "public:/2019-09/MessageExamples.txt",
                },
				...
	]
Code Block
languagejs
titlecase 2 - no code example provided

A complete JSON example is available in page JSON example - Donlon TOBT Setting service description.