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 8 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

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

In JSON the service behaviour is expressed per service interface.

This may be complemented by a service SERVICE_BEHAVIOUR_DESCRIPTION document.


tip

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.


Per service interface (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

As a 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.

JSON example

behaviour 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"
                    }
            ]
			...
			}
	]
behaviour 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.

  • No labels