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 description coverage

Identifier

SWIM-SERV-001

Requirement

A service description shall describe a single service.

Rationale

The readability of any service description is improved by keeping it focussed on one service.

Verification

Completeness: Not Applicable.

Consistency: Not Applicable.

Correctness: Verify that one and only one service is described.

Examples/Notes


Level of Implementation

Mandatory


Guidance

No guidance is provided for the general case.

Case of a composed service

Case where the described service is composed of other services, consists of underlying services, such as for an orchestration.

The objective of the service description is to describe the composed service as a single service, in order for the service consumer to make good use of that composed service.

Information on the underlying services may be added, but is not required by the specification.

It is good SOA practice that a service appears as a black-box to its consumers.

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
	"id": "http://www.eurocontrol.int/schemas/servicedescription/0.0.3",
	"type": "object",
	"additionalProperties": false,
	"required": ["informationService"],
	"properties":
	{
		"informationService":
		{
			"description" : "the description of an information service [SWIM-SERV-001]",
			"$ref" :  "#/definitions/InformationService"
		}
	},
	

		"InformationService" : 
		{
			"description" : "A type of service that provides an ATM information sharing capability.",
			"type": "object",
			"additionalProperties": false,
			"required": ["descriptionInformation", "name", "version", "serviceAbstract", "serviceProvision", "serviceCategorisation", "serviceGeneralDescription", "serviceInformationDescription", "serviceTechnicalDescription", "serviceDescriptionReferences", "serviceInterface"],
			"properties":
			{
				"descriptionInformation":
				{
					"description" : "A container for Service Description metadata.",
					"$ref" : "#/definitions/DescriptionInformation",
					"SemanticCorrespondence" : "No Semantic Correspondence established"
				},
				"name":
				{
					"description" : "A piece of identifying information that gives stakeholders a way to reference or identify a service. [SWIM-SERV-006]",
					"type" : "string",
					"minLength":1
				},
				"version":
				{
					"description" : "The version of the information service. [SWIM-SERV-006]",
					"type" : "string",
					"minLength":1
				},
				"serviceAbstract":
				{
					"description" : "A brief summary of the service offering. [SWIM-SERV-007]",
					"type" : "string",
					"minLength":1
				},
				"serviceProvision":
				{
					"description" : "A container for information about who provides the service, when and how it is supported.",
					"$ref" : "#/definitions/ServiceProvision"
				},
				"serviceCategorisation":
				{
					"description" : "A taxonomy used to classify a service by the type of service provided or by some other technological or architectural solution. [SWIM-SERV-009]",
					"$ref" : "#/definitions/ServiceCategorisation"
				},
				"serviceGeneralDescription":
				{
					"description" : "A container for information about what the service provides, its purpose and under which conditions and quality levels it is provided.",
					"$ref" : "#/definitions/ServiceGeneralDescription"
				},
				"serviceInformationDescription":
				{
					"description" : "A container for the description of the information exchanged by the information service.",
					"$ref" : "#/definitions/ServiceInformationDescription"
				},
				"serviceTechnicalDescription":
				{
					"description" : "A container for information about the security mechanisms, technical constraints and monitoring of the information service.",
					"$ref" : "#/definitions/ServiceTechnicalDescription"
				},
				"serviceInterface":
				{
					"description" : "The means by which the underlying capabilities of a service are accessed.",
					"type" : "array",
					"items" : { "$ref":"#/definitions/Interface" },
					"minItems": 1
				},
				"serviceDescriptionReferences":
				{
					"description" : "A container for references to documents describing specific aspects of the service instance.",
					"$ref" : "#/definitions/ServiceDescriptionReferences"
				}
			}
		},
Expand
titleRules [+]

Rules expressed for the cases as defined in Registry URD.

caserules
COMPLIANTMandatory
CANDIDATEsame
DEFINITIONsame

Guidance

Rationale: The readability of a service description is improved by keeping it focused on one service.

At highest level, create an object with the single attribute informationService.

Example

Code Block
languagejs
{
    "informationService": {
	...
	}
}


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