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

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 6 Next »


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

JSON 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

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.

  • No labels