Page Table of Content

Requirement

Title	Service messages
Identifier	SWIM-SERV-280
Requirement	A service description shall include or refer to information about the messages that are exchanged by the service including input, output and error messages.
Rationale	The consumer needs to know which service messages are used.
Verification	Completeness: Verify that all service messages are described. Consistency: Not Applicable. Correctness: Not Applicable.
Examples/Notes	Note: Service messages may be linked to service operations. Example input message: TOBTSettingRequest. Message that provides the Target Off-Block Time value of a specific flight. Example output message: TOBTSettingResponse. Message that responds the validity of a previously sent TOBTSettingRequest message. Example error message: invalidFlight.
Level of Implementation	Mandatory

Guidance

The specification allows flexibility in describing the technical view of the interactions with the service. This is illustrated below. For example:

some service designs do not rely on interfaces or operations for their interactions.
it is possible to define input and output message as part of service interfaces when no operations are exposed.

-

HTTP error codes are covered by SWIM-SERV-220 Service behaviour. The Examples/Notes in the requirement box suggests that they are covered in the detailed model view. However, there is nothing in the service metadata schema to stop you adding a new behaviour field with a name set to, e.g., “Error Handling”.

Verification Support

Completeness

Check that:

[ ] The service description includes or refers to information about the input messages that are exchanged by the service.

[ ] The service description includes or refers to information about the output messages that are exchanged by the service.

[ ] The service description includes or refers to information about the error messages that are exchanged by the service.

Examples

The following example shows the content as a table.

service messages	message	name	TOBTSettingRequest
		description	Message which provides the Target Off-Block Time value of a specific flight.
		data format	https://donlon.eu/schema/1.0.0/tobt/donlon-schema.xsd
	message	name	TOBTSettingResponse
		description	Message which responds the validity of a previously sent TOBTSettingRequest message.
		data format	https://donlon.eu/schema/1.0.0/tobt/donlon-schema.xsd
	message	name	TOBTDeleteRequest
		description	Message which requests deleting the last TOBT value of the specified flight.
		data format	https://donlon.eu/schema/1.0.0/tobt/donlon-schema.xsd
	message	name	TOBTDeleteResponse
		description	Message which responds the validity of a previously sent TOBTDeleteRequest message.
		data format	https://donlon.eu/schema/1.0.0/tobt/donlon-schema.xsd
	message	name	TOBTErrorReponse
		description	Error message in response to a user query.
		data format	https://donlon.eu/schema/1.0.0/tobt/donlon-schema.xsd
		isError	true

The following example shows an extract of the content of a JSON file that conforms to the Service Metadata Schema

The example contains the schema field for completeness. This is required by SWIM-SERV-260 Service interface protocols and data format.

Example of SWIM-SERV-280 using Service Metadata Schema

"serviceInterface": [{
 "messages": [{
  "name": "TOBTSettingRequest",
  "description": "Message which provides the Target Off-Block Time value of a specific flight.",
  "schema": {
   "url": "https://donlon.eu/schema/1.0.0/tobt/donlon-schema.xsd" } }, 
 { 
  "name": "TOBTSettingResponse", 
  "description": "Message which responds the validity of a previously sent TOBTSettingRequest message.", 
  "schema": { "url": "https://donlon.eu/schema/1.0.0/tobt/donlon-schema.xsd" } }, 
 { 
  "name": "TOBTDeleteRequest", 
  "description": "Message which requests deleting the last TOBT value of the specified flight.", 
  "schema": { "url": "https://donlon.eu/schema/1.0.0/tobt/donlon-schema.xsd" } }, 
 { 
  "name": "TOBTDeleteResponse", 
  "description": "Message which responds the validity of a previously sent TOBTDeleteRequest message.", 
  "schema": { "url": "https://donlon.eu/schema/1.0.0/tobt/donlon-schema.xsd" } 
 },
 {
  "name": "TOBTErrorReponse",
  "description" : "Error message in response to a user query.",
  "schema": {
   "url": "https://donlon.eu/schema/1.0.0/tobt/donlon-schema.xsd"
  },
  "isError": true
 }
] 
}]

Complete examples are available at Example service description.

SWIM Supporting Material

SWIM-SERV-280 Service messages

Requirement

Guidance

Verification Support

Examples

Related content