Requirement

Title

Service interface protocols and data format

Identifier

SWIM-SERV-019

Requirement

A service description shall include the list of service interface protocols (including name and version) and data format to be used.

Rationale

Makes explicit within the service description what the protocols are.

Verification

Completeness: Verify that all relevant protocols and versions are listed; verify that the information is provided for each provider side and consumer side interface.

Consistency: Verify that the protocols are consistent with the selected interface binding.

Correctness: Not Applicable.

Examples/Notes

Note: The list of supported protocols are the ones corresponding to the selected interface binding. The supported versions of the protocols need to be declared. E.g. version of the Transport Level Security (TLS).

Level of Implementation

Mandatory

Guidance

Examples

See the Service interface protocols and data format section within the Donlon TOBT Setting Service Description.

Guidance for JSON service description 

UNDERWORK

Schema

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

		"ServiceInformationDescription" : 
		{
			"description" : "A container for the description of the information exchanged by the information service.",
			"type": "object",
			"additionalProperties": false,
			"required": ["informationDefinition", "exchangeSchema"],
			"properties":
			{
				"informationDefinition":
				{
					"description" : "A formal representation of information concepts or data concepts. [SWIM-SERV-022]",
					"type" : "array",
					"items" : { "$ref":"#/definitions/InformationDefinition" },
					"minItems": 1
				},
				"exchangeSchema":
				{
					"description" : "Formal description of the data involved in an information exchange.",
					"type" : "array",
					"items" : { "$ref":"#/definitions/ExchangeSchema" },
					"minItems": 1
				}
			}
		},


		"InformationDefinition" : 
		{
			"description" : "A formal representation of information concepts or data concepts. [SWIM-SERV-022]",
			"type": "object",
			"additionalProperties": false,
			"required": ["name", "description", "airmConformant"],
			"properties":
			{
				"name":
				{
					"description" : "The name of the Information Definition. [SWIM-SERV-022]",
					"type" : "string",
					"minLength":1
				},
				"description":
				{
					"description" : "The description of the Information Definition. [SWIM-SERV-022]",
					"type" : "string",
					"minLength":1
				},
				"airmConformant":
				{
					"description" : "An indication whether the information definition used by the service conforms to the ATM Information Reference Model. [SWIM-SERV-023]",
					"type" : "boolean"
				},
				"airmVersion":
				{
					"description" : "The applicable version of the ATM Information Reference Model. [SWIM-SERV-023]",
					"type" : "string"
				}
			}
		},


		"ExchangeSchema" : 
		{
			"description" : "Formal description of the data involved in an information exchange.",
			"type": "object",
			"additionalProperties": false,
			"required": ["name", "reference", "schemaLanguage"],
			"properties":
			{
				"name":
				{
					"description" : "The name of the exchange schema. [SWIM-SERV-019]",
					"type" : "string",
					"minLength":1
				},
				"schemaLanguage":
				{
					"description" : "Description of the language used (e.g. XML, JSON). [SWIM-SERV-019]",
					"type" : "string",
					"minLength":1
				},
				"reference":
				{
					"description" : "A reference to the exchange schema containing the specifications of the data structures. [SWIM-SERV-019].",
					"type" : "string",
					"minLength":1
				}
			}
		},

Rules expressed for the cases as defined in Registry URD.

caserules
COMPLIANTmandatory
CANDIDATEsame
DEFINITIONsame


Guidance


Within field informationDefinition (itself within field serviceInformationDescription) list one or more occurrences of type InformationDefinition.




attribute namedescriptiontypeguidancerule
---A container for the description of the information exchanged by the information service.---

Rationale: Provide a description of the information/data that is exchanged by the service.

Guidance: SWIM-SERV-019 Protocols and data format requires a description of the elements of the exchanged information. This is provided here. It can be provided by reference and can make use of a published information exchange model. Therefore, use the option best suited to your service.

(M)
informationDefinitionA formal representation of information concepts or data concepts. [SWIM-SERV-022]InformationDefinitionRational: Enables to understand the information provided by the service, with a specific focus to the semantics of the informationMandatory
exchangeSchemaFormal description of the data involved in an information exchange.ExchangeSchemaRational: Enables to understand data structure, and should include definition documents (XSD, JSON Schema,).Mandatory








InformationDefinition - Mandatory

A formal representation of information concepts or data concepts. [SWIM-SERV-022]

Rational: Enables to understand the information provided by the service, with a specific focus to the semantics of the information


attribute namedescriptiontypeguidancerule
nameThe name of the Information Definition. [SWIM-SERV-022]stringGuidance: Provide a name that indicates which part of all the information exchanged by the service is going to be described. In the absence of multiple parts a generic name can be provides e.g. Information DefinitionMandatory
descriptionThe description of the Information Definition. [SWIM-SERV-022]string

Guidance: introduce this information definition. Eg use the information definition abstract SWIM-INFO-005 Information definition scope.

Guidance: Make sure to have one or several service documents with type INFORMATION_DEFINITION. See Guidance on serviceDocument.

Mandatory
airmConformantAn indication whether the information definition used by the service conforms to the ATM Information Reference Model. [SWIM-SERV-023]boolean

Guidance: Indicate whether the service payload has semantic correspondence with the AIRM.


Mandatory
airmVersionThe applicable version of the ATM Information Reference Model. [SWIM-SERV-023]string

Rule: Mandatory when airmConformant is true. No use otherwise.

Guidance: Version of the AIRM that was used to establish semantic correspondence.

Whether stand-alone or integrated, make sure the semantic correspondence is made available in a service document with type INFORMATION_DEFINITION.


Conditional Mandatory




ExchangeSchema - Mandatory


attribute namedescriptiontypeguidancerule
---Formal description of the data involved in an information exchange.---

Rational: Enables to understand data format(s), and should include definition document(s) (XSD, JSON Schema,).

Question: how far is this covering the requirement SWIM-SERV-020 Machine-readable interface as well?

(M)
nameThe name of the exchange schema. [SWIM-SERV-019]stringGuidance: Provide a clear name that represents the data format that is used by the service.Mandatory
schemaLanguageDescription of the language used (e.g. XML, JSON). [SWIM-SERV-019]stringGuidance: Indicate the language in which the data format is expressed (e.g. XSD, JSON, natural language,..)Mandatory
referenceA reference to the exchange schema containing the specifications of the data structures.string

Guidance: Indicate with a reference the location of where the data format is defined (e.g. See Documents section )

Question: Is this not redundant with service documents of type MACHINE_READABLE_SERVICE_DESCRIPTION? see Guidance on serviceDocument.

Mandatory



Example

		"serviceInformationDescription": {
			"informationDefinition": [
				{
					"name": "Service Information Definition",
					"description": "The information definition is described in a separate document. This includes the semantic correspondence. See References.",
					"airmConformant": true,
					"airmVersion": "1.0.0"
				}
			],
			"exchangeSchema": [
				{
					"name": "TOBT Setting Schema",
					"reference": "This schema defines the data structures used to exchange data with the service.\r\nSee Service_References.",
					"schemaLanguage": "XML"
				}
			]
		},


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