Requirement

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 

Schema

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

			"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 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.

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

	"serviceDocument": [
                {
                    "documentType": "CODE_EXAMPLE"
                    "title": "Example of messages",
                    "version": "1.0",
                    "description": "A set of message examples",
                    "reference": "public:/2019-09/MessageExamples.txt",
                },
				...
	]

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