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


Requirement

Title

Information definition

Identifier

SWIM-SERV-022

Requirement

A service description shall describe the elements of the exchanged information including:

  • the name of the element;
  • the definition of the element;
  • the cardinality applicable to the element, including whether the element is optional, conditional or mandatory in the exchange;
  • constraints applicable to the element, such as:
    • datatype;
    • value ranges;
    • special values;
    • character set restrictions;
  • the semantic correspondence of the element with the AIRM; and
  • the structure and relevant relationships between the elements.

Rationale

This requirement ensures that the precise meaning of the exchanged information is shared by all parties of the information exchange.

Verification

Completeness: Verify that the service description describes all elements of the exchanged information and that the required details are provided.

Consistency: Verify that the elements are consistent with each other and with the AIRM concepts used in the semantic correspondence.

Correctness: Not Applicable.

Examples/Notes

Note: The service description must describe all elements of the exchanged information at all levels, down from the service operation parameters to attributes and data types.

Note: It is best practice to base the information definition  on the requirements found in the EUROCONTROL Specification for SWIM Information Definition [RD 2], ensuring that it contains the extra details required by this requirement.

Note: The information definition can be provided by reference, for example when using an AIRM conformant standardised information exchange models, such as Aeronautical Information Exchange Model (AIXM) [RD 15] and ICAO Meteorological Information Exchange Model (IWXXM) [RD 16].  

Level of Implementation

Mandatory


Guidance

This requirements sets out the minimum detail needed to describe each element of the information that is exchanged. For example, if the exchange involves information about "aerodromes" the "aerodrome" element type should be described. This means the element type should be given a name, a description, etc based on the bulleted list in the requirement. The result is called an information definition.

Most of the details required are self-explanatory. The semantic correspondence of the element type with the AIRM is established following the requirements found in the Guidance on semantic correspondence section of the SWIM Information Definition Handbook.

The information definition should be complete, covering all of the element types that are exchanged, including a definition of service operation parameters, attributes and data types. However, the information definition can be provided in several ways e.g.:

  • embedded into the service description
  • by reference to an external document
  • by reference to a standardised information exchange model.

Regardless of the option chosen, SWIM-SERV-023 AIRM conformance requires that the service description contains a statement on its AIRM conformance. This requirement affects SWIM-SERV-022; the information definition shall follow the semantic correspondence requirements in the EUROCONTROL Specification for SWIM Information Definition in order to provide evidence of its AIRM conformance.

Best Practice

It is best practice to base the information definition on the requirements found in the EUROCONTROL Specification for SWIM Information Definition, ensuring that it also contains the extra details required by this requirement.

The EUROCONTROL Specification for SWIM Information Definition requires less detail to be provided for each element type: SWIM-INFO-007 Information definition concepts requires only a name, definition and (if needed) a data type.

However, the specification also goes beyond what is asked for by the EUROCONTROL Specification for SWIM Service Description. For example, it requires that each element type has a unique identifier (SWIM-INFO-008 Unique identifiers for concepts) and a dedicated namespace.

Examples

See the Information Definition section within the Donlon TOBT Setting Service Description.

Guidance for JSON service description 

tentative JSON Guidance

scope

The guidance below includes guidance for requirement SWIM-SERV-023 AIRM conformance.


Schema

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

 Schema excerpt [+]
		"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
				},

			}
		},


		"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"
				}
			}
		},
 Rules [+]

Rules expressed for the cases as defined in Registry URD.

caserules
COMPLIANTmandatory
CANDIDATE
DEFINITION


Guidance

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

InformationDefinition - Mandatory

A formal representation of information concepts or data concepts. 

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.stringProvide 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.string

Introduce this information definition.

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.boolean

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

This attribute is for requirement SWIM-SERV-023 AIRM conformance

Mandatory
airmVersionThe applicable version of the ATM Information Reference Model.string

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

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

Note: Whether stand-alone or integrated, make sure the semantic correspondence is made available in a service document (see below).

This attribute is for requirement SWIM-SERV-023 AIRM conformance

Mandatory Conditional


Information Definition document - Mandatory 

The JSON Schema does not include attributes to describe all elements exchanged. The full description of the information definition is provided as a service document.

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

semantic correspondence

When the semantic correspondence is a separate document from the Information Definition, create one or more instances of Document with type AIRM_TRACE (in addition to the document(s) with type INFORMATION_DEFINITION).

See Guidance on serviceDocument on how to fill in documents.

Example

Semantic correspondence within info defn

		"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"
				}
			],

		}


			"serviceDocument": [
				{
					"documentType": "INFORMATION_DEFINITION",
					"title": "TOBT Setting Information Definition",
					"version": "1.0",
					"description": "Information Definition for the DONLON TOBT Setting service. Includes Semantic correspondence with traces to the AIRM",
					"reference": "public:/2019-09/InformationDefinition.txt"
				}
			]

Semantic correspondence separate from info defn

		"serviceInformationDescription": {
			"informationDefinition": [
				{
					"name": "Service Information Definition",
					"description": "The information definition is described in a separate document. The semantic correspondence is still another document. See References.",
					"airmConformant": true,
					"airmVersion": "1.0.0"
				}
			]

		}


			"serviceDocument": [
				{
					"documentType": "INFORMATION_DEFINITION",
					"title": "TOBT Setting Information Definition",
					"version": "1.0",
					"description": "Information Definition for the DONLON TOBT Setting service. Without AIRM Semantic correspondence.",
					"reference": "public:/2019-09/InformationDefinition.txt"
				},
				{
					"documentType": "AIRM_TRACE",
					"title": "TOBT Setting Semantic Correspondence",
					"version": "1.0",
					"description": "AIRM Semantic correspondence for the DONLON TOBT Setting service",
					"reference": "public:/2019-09/TraceToAIRM.txt"
				}
			]


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

  • No labels