Requirement

Title

Model view

Identifier

SWIM-SERV-026

Requirement

A service description should

  • include a model view on the conceptual parts, expressed using a formal and standardised notation, that formalises the representation of the business logic of its service interfaces, service operations and exchanged information; and
  • declare the notation used to express the model view.

Rationale

Exposing the business logic of the service in a formalised notation and standardised notation allows operational and technical experts to understand how the service works and make comparisons.

Verification

Completeness: If the model view is provided, verify that the notation is declared; and verify that the model view fully covers service interfaces, service operations and exchanged information.

Consistency: If the model view is provided, verify that the model view is consistent with the service description (e.g. same service operation name).

Correctness: If the model view is provided, verify that the model view is aligned with the declared notation.

Examples/Notes

Note: It is recommended to use the UML as notation.

Note: The model view covers structural and activity diagrams when using UML as notation.

Note: The SESAR ISRM Foundation 8 is an example of a formal and standardised notation [RD 6].

Level of Implementation

Recommended

Guidance

Tip on Level of Implementation

The requirement recommends to provide a model view, which usefulness was emphasised during consultation. The requirement is not defined as mandatory in order not to exclude services for which no such model exists

Guidance for JSON service description 

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

Guidance

Two cases must be distinguished depending on whether model view is being provided or not.

Case 1 - Model view is provided

Within "serviceDocument" field (itself within "serviceDescriptionReferences" field) create one or more instances of Document with type SERVICE_MODEL .

See Guidance on serviceDocument on how to fill in documents.

Case 2 - No model view is provided

Nothing to be mentioned in the JSON service description

Example

See Guidance on serviceDocument for examples of documents.