SWIM Supporting Material
SWIM-SERV-290 Information definition - minimum
- WILSON Scott
Requirement
Title | Information definition (minimum) |
Identifier | SWIM-SERV-290 |
Requirement | A service description shall include or refer to the following information about the exchanged information service payload:
|
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 3], ensuring that it contains the extra details required by this requirement. Note: The information definition can be provided by one or more reference, for example when using an AIRM conformant standardised information exchange models, such as Aeronautical Information Exchange Model 5.1.1 (AIXM) [RD 9] and ICAO Meteorological Information Exchange Model (IWXXM) 3.0.0 [RD 10]. Note: Data types are expected for, e.g., attributes of classes. The classes themselves tend not to have data types. |
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, 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.
Format of information definitions
The EUROCONTROL Specification for SWIM Information Definition does not require a specific format for an information definition. Some example formats are provided at SWIM-INFO-001 Need for information definitions. From a service description perspective this allows a degree of flexibility. For example, a JSON schema or XML schema is an acceptable mean of compliance if the schema provides all required information.
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.
Verification Support
| Completeness | Check that: [ ] The service description includes or refers to information about the exchanged information service payload. [ ] The information about the exchanged information service payload includes the name of the elements. [ ] The information about the exchanged information service payload includes the definition of the elements. [ ] The information about the exchanged information service payload includes the data type used by the elements if applicable. [ ] The information about the exchanged information service payload includes the semantic correspondence of the elements with the AIRM. |
| Consistency | Check that: [ ] The elements are consistent with each other and with the AIRM concepts used in the semantic correspondence. |
Examples
The following example shows the content as a table.
| information definition | https://ext.eurocontrol.int/swim_confluence/display/SWIM/Example+service+description+-+information+elements |
|---|
The following example shows an extract of the content of a JSON file that conforms to the Service Metadata Schema
"informationDescription": {
"informationDefinition": {
"reference": [{
"description": "Service Information Definition",
"url": "https://ext.eurocontrol.int/swim_confluence/display/SWIM/Example+service+description+-+information+elements"
}]
}
}
The following example shows how an information exchange model can be used.
"informationDescription": {
"informationDefinition": {
"reference": [{
"description": "Aeronautical Information Exchange Model (AIXM) 5.1.1",
"url": "https://www.aixm.aero/schema/5.1.1/index.html"
},
{
"description": "Event Extension for AIXM 5.1.1",
"url": "https://www.aixm.aero/schema/5.1.1/event/version_5.1.1-i/Event_Features.xsd"
}]
}
}
The following example shows how the information definition can be included in the service description. The example incorporates the elements from SWIM-SERV-300 Information definition - extended. It is based on the Example service description - information elements.
"informationDescription": {
"informationDefinition": [{
"name": "ICAOFlightIdentification",
"definition": "Flight identification structure based on usual ICAO fields present in the Flight Plan.",
"airmCorrespondence": "out of scope - container"
},{
"name": "aircraftIdentification",
"definition": "Name used by ATS units to identify and communicate with the aircraft.",
"airmCorrespondence": "urn:aero:airm:1.0.0:LogicalModel:Subjects:Flight:FlightIdentifier:AircraftIdentification",
"cardinality": "1",
"datatype": "AircraftIdentification",
"constraints": "String of 1 to 7 alphanumeric characters.",
"path": "ICAOFlightIdentification.aircraftIdentification"
}]
}
The following example shows the use of the path field to capture structure and relationships for SWIM-SERV-300 Information definition - extended. It includes an entity called ICAOFlightIdentification, a property of that entity called aircraftIdentification and a specialisation of that entity called NMICAOFlightIdentification.
"informationDescription": {
"informationDefinition": [
{
"name": "ICAOFlightIdentification",
...
"path": "ICAOFlightIdentification"
},
{
"name": "aircraftIdentification",
...
"path": "ICAOFlightIdentification.aircraftIdentification"
},
{
"name": "NMICAOFlightIdentification",
...
"path": "NMICAOFlightIdentification (specialises ICAOFlightIdentification)"
}
]
}
Complete examples are available at Example service description.
Status: Living Material