SWIM Supporting Material

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 4 Next »


Requirement

Title

Service behaviour

Identifier

SWIM-SERV-025

Requirement

A service description shall include information on the behaviour of the service including:

  • the sequence of service operations; and
  • the handling of unexpected behaviour.

Rationale

This requirement facilitates the understanding of the service behaviour, including the sequencing of service operations to support operational processes, and the error handling. 

Verification

Completeness: Verify that the behaviour information is included and covers the errors handling as well.

Consistency: Verify that the names of the interfaces, service operations and exchanged information are consistent with the interface definitions.

Correctness: Not Applicable.

Examples/Notes

Examples of behaviour specification:

  • The behaviour under normal conditions;
  • The behaviour with incorrect input data (e.g., out of range or incorrect data type);
  • The use of error messages, and error handling in general;
  • The list of error codes and expected effects.

Note: The service behaviour can be captured in formal modelling notations such as a Unified Modeling Language (UML) sequence diagram, and/or expressed as textual description in plain language.

Level of Implementation

Mandatory

Guidance

Examples

See the Service behaviour section within the Donlon TOBT Setting Service Description.

Guidance for JSON service description 

tentative JSON Guidance

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

Schema

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

 Schema excerpt [+]
		"Interface" : 
		{
			"description" : "The means by which the underlying capabilities of a service are accessed. [SWIM-SERV-016]",
			"type": "object",
			"additionalProperties": false,
			"required": ["name", "description", "interfaceProvisionSide", "tiPrimitiveMessageExchangePattern", "endPoint", "serviceInterfaceBinding", "networkInterfaceBinding", "interfaceBindingDescription", "operation", "behaviour"],
			"properties":
			{
				"behaviour":
				{
					"description" : "The manner in which a service operates under normal and unexpected conditions. [SWIM-SERV-025]",
					"type" : "array",
					"items" : { "$ref":"#/definitions/ServiceBehaviour" },
					"minItems": 1
				},
				...
		},


		"ServiceBehaviour" : 
		{
			"description" : "The manner in which a service operates under normal and unexpected conditions. [SWIM-SERV-025]",
			"type": "object",
			"additionalProperties": false,
			"required": ["name", "description"],
			"properties":
			{
				"description":
				{
					"description" : "The description of the service behaviour. [SWIM-SERV-025]",
					"type" : "string",
					"minLength":1
				},
				"name":
				{
					"description" : "The name of the service behaviour. [SWIM-SERV-025]",
					"type" : "string",
					"minLength":1
				}
			}
		},





			"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
CANDIDATEsame
DEFINITIONsame

Guidance

Examples of behaviour specification:

  • The behaviour under normal conditions;
  • The behaviour with incorrect input data (e.g., out of range or incorrect data type);
  • The use of error messages, and error handling in general;
  • The list of error codes and expected effects.


Note: The behaviour description may refer to a SERVICE_BEHAVIOUR_DESCRIPTION document.

Note: The service behaviour can be captured in formal modelling notations such as a Unified Modeling Language (UML) sequence diagram, and/or expressed as textual description in plain language.

Mandatory behaviour per interface

Guidance: provide one or more behaviours.

Note: The behaviour description may refer to a SERVICE_BEHAVIOUR_DESCRIPTION document.

Note: Behaviour often concerns closely related operations in the same interface. Would behaviour relate operations from different interface, feel free to describe it in one of the concerned interface.

The manner in which a service operates under normal and unexpected conditions. [SWIM-SERV-025]

Mandatory, minItems=1


attribute namedescriptiontypeguidancerule
nameThe name of the service behaviour. [SWIM-SERV-025]string: provide a short name for the behaviourMandatory
descriptionThe description of the service behaviour. [SWIM-SERV-025]string

Guidance:

Describe the behaviour as

  • the sequence of service operations; and
  • the handling of unexpected behaviour.

And / or make reference to a SERVICE_BEHAVIOUR_DESCRIPTION document.

Mandatory

Optional behaviour document(s) 

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.

JSON example

case 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",
                },
				...
	]
case 2 - no code example provided
	"behaviour": [
                    {
                        "name": "nominal behaviour",
                        "description": "Each operation of the interface can be called independently.\r\nThe following diagram illustrates the interaction between the service consumer and the service"
                    }
                ],


	"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

Status: Working Material