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

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 

Excerpt

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

Schema

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

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

Rules expressed for the cases as defined in Registry URD.

caserules
COMPLIANTmandatory
CANDIDATEsame
DEFINITIONsame

Guidance

Additional attributes to Interface type as described in SWIM-SERV-016 Service interfaces

In JSON the service behaviour is expressed per service interface.

This may be complemented by a service SERVICE_BEHAVIOUR_DESCRIPTION document.


Tip
titletip

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.

In the latter case, whether for a model file or for a document with diagrams, use a SERVICE_BEHAVIOUR_DESCRIPTION document.

Interface - additional attribute

Additional attribute to Interface type as described in SWIM-SERV-016 Service interfaces

Note
titleservice vs interface

In the Schema the service behaviour is split per interface.

  • This is often ok, as the behaviour often concerns closely related operations in the same interface.
  • When behaviour concern relate operations from various interfaces, feel free to describe it in one of the concerned interface.
Info
titleBehaviour document

Service behaviour may be made available as a service document.

  • This allows in particular to add (sequence) diagrams.
attribute namedescriptiontypeguidancerule
behaviourThe manner in which a service operates under normal and unexpected conditions.ServiceBehaviour

Provide one or more behaviours.

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

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.

Mandatory, minItems=1

Behaviour - Mandatory

It is mandatory to provide one or more service behaviour(s) for each interface.

Notes:

  • Service behaviour often concerns closely related operations in the same interface.   When service behaviour relate operations from different interfaces, feel free to describe it in one of the concerned interfaces.
  • When service behaviour is made available in a document, make this clear in the behaviour.description of each interface


attribute namedescriptiontypeguidancerule
nameThe name of the service behaviour.stringProvide a short name for the behaviourMandatory
descriptionThe description of the service behaviour.string

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

Behaviour document - Optional 

Service behaviour may be provided as a document of type SERVICE_BEHAVIOUR_DESCRIPTION.

See Guidance on serviceDocument on how to fill in documents.

Example

Code Block
languagejs
titlebehaviour without document
	"serviceInterface": [
            {
			
			"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"
                    }
            ]
			
			}
	]
Code Block
languagejs
titlebehaviour with document
	"serviceInterface": [
            {
			
			"behaviour": [
                    {
                        "name": "behaviour document",
                        "description": "The service behaviour is fully described in the SERVICE_BEHAVIOUR_DESCRIPTION document"
                    }
                ]
			
			}
	]

	"serviceDocument": [
                {
                    "documentType": "SERVICE_BEHAVIOUR_DESCRIPTION "
                    "title": "Service Behaviour",
                    "version": "1.0",
                    "description": "",
                    "reference": "... ...",
                }		
	]

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