Requirement

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

tentative JSON Guidance

Guidance for JSON service descriptions integrated within the SWIM Service Description Handbook.

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

case	rules
COMPLIANT	optional
CANDIDATE	same
DEFINITION	same

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

message example

Use document type CODE_EXAMPLE even for message examples. Usage of document type "MESSAGE_EXAMPLE is deprecated.

Case 2 - No example is provided

Nothing to mention in the JSON service description

JSON example

case 1 - examples are provided

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

Page tree

SWIM-SERV-029 Examples of code