Service description coverage SWIM-SERV-001 A service description shall describe a single service. The readability of any service description is improved by keeping it focussed on one service. Not Applicable. Not Applicable. Verify that one and only one service is described. Service description language SWIM-SERV-002 The textual descriptions in a service description shall be written in English using the spelling listed as the primary British spelling when conflicting spellings exist. By using a single reference language, the risk of translation ambiguities when comparing service descriptions is removed. Not Applicable. Not Applicable. Verify that the textual descriptions are correct British English. Note: This requirement does not apply to implementation details that are reflected in the content of the service description e.g. service operation names. Define abbreviations and acronyms SWIM-SERV-003 A service description shall define all used abbreviations and acronyms and be in accordance with the AIRM abbreviation list [RD 4]. It is best practice to document all abbreviations and acronyms used in a document. Verify that all used acronyms and abbreviations are defined in the service description. For abbreviations/acronyms existing in AIRM, verify that the definitions are the same. Not Applicable. Note: It is allowed to use abbreviations/acronyms not defined in AIRM abbreviation list [RD 4]. However, when using one of those, their definitions must be the same. Use standard abbreviations and acronyms SWIM-SERV-004 A service description should only use standard abbreviations and acronyms. It is best practice to use standard abbreviations and acronyms only. Using non-standard abbreviations and acronyms makes the reading more difficult and may confuse the reader. Not Applicable. Verify that the acronyms and abbreviations have same definitions as in their source. Not Applicable. Note: This applies to ATM and non-ATM abbreviations and acronyms. Example sources for standard abbreviations and acronyms: ATM: ICAO and AIRM; Non-ATM: ISO. Service description identification SWIM-SERV-005 A service description shall include: a title by which the service description is known; an edition; and a reference date for use in citing the service description. This requirement supports the identification and citation of a service description. Verify that the 3 elements are included. Not Applicable. Not Applicable. Example service description identification: 'Flight Management service description, edition 20.0, 14 Mar 2016'. Note: The edition of the service description is not to be confused with the version of the service. A service description can evolve to a new edition while still describing the same service version. Service identification SWIM-SERV-006 A service description shall include: the name of the service; and the version of the service. This requirement makes clear what the subject of the service description is. It supports the identification and citation of the service being described. Verify that the 2 elements are included Not Applicable. Not Applicable. Example service identifications: 'TargetOffBlockTimeSetting service, version 1.3.0'; 'FlightManagement service, version 20.0'. Note: To improve readability across service descriptions, it is best practice to apply following conventions for a service name: include the operational concept supported or the information being exchanged; be a maximum of five words in length; be represented using UpperCamelCase, and not use snake_case; and not end with the ‘service’ suffix. Service abstract SWIM-SERV-007 A service description shall include an abstract as a small textual description in plain language summarising the service. A good abstract is valuable, in particular during service discovery. This requirement supports the decisions on whether the described service is suitable for use in a particular situation. Verify that the element is included. Not Applicable. Not Applicable. Note: It is best practice for an abstract to summarise the information provided elsewhere in the service description and not to bring any new information. Service provider SWIM-SERV-008 A service description shall include the following information about the service provider: the name and description of the organisation responsible for the service; and one or more points of contact where additional information can be obtained, including name, contact information and role. Knowing the service provider is essential to business experts. Point of contact allows getting additional information regarding the service. Verify that the elements are included. Not Applicable. Not Applicable. Example contact information: email address; postal address; phone number; URL. Example points of contact: 'Customer Relations, to request access to the service, http://www.donlon-airport.com/swim/service-request'; 'Service Desk, to report incidents on services in operation, contact [24/7] +693 555 01 service-desk@donlon-airport.com'. Note: Consider including information on provider certification when relevant for the service being described (e.g. for a Meteorological service). Service categories SWIM-SERV-009 A service description shall include the categories to which the service belongs based on the PCP information exchange areas: Aeronautical information exchange; Meteorological information exchange; Cooperative network information exchange; Flight information exchange. Service category information allows discovering services by a series of classification criteria. This requirement supports decision making in terms of service suitability in relation to a particular usage context. Verify that the PCP category is present. Not applicable. Not Applicable. Note: It is best practice to include additional category information, and state the service categorisation scheme used, by inclusion or reference. The SESAR 1 ISRM Portfolio [RD 5] is a good source for service categories. Service standard reference SWIM-SERV-010 A service description shall include a statement indicating whether the service adheres to a service standard; and if so, a reference to the service standard; a statement on any implemented options of the service standard; and a statement on any deviation from the service standard. The reference to standards is essential information, fostering reuse. Verify that the statement about adherence to a reference standard is included. If the service adheres to a service standard, verify that the reference to the service standard is included. Not Applicable. Example service standard references: 'EUROCAE Arrival Sequence standardised service design, version 1.0'; 'Not adherent to a service standard'. Operational needs SWIM-SERV-011 A service description shall include information about the operational needs fulfilled by the service; indicate whether information exchange requirements (IER) were used in the identification of the needs for the service; and if so include or refer to the information exchange requirements (IER). Operational needs relate to the operational context in which the service is used. IERs reference the requirements that are at the origin of the service. This requirement supports decision making in terms of service suitability within a particular operational context. Verify that operational needs are included; verify that the indication on whether IERs were used is included. If IERs were used, verify that the IERs and the source(s) are included. if a source is included, verify that the IERs are available in the referenced source. Example operational need: 'The Flight Management service fulfils the need to retrieve information about flights and flight plans and the need to provide information about changes in flights'. Note: When describing operational needs, it is best practice to add a reference to an operational concept document, or contextual description. Example IERs: 'It shall be possible for the end user to access up-to-date network weather forecasts (up to D-10) in the specified geographical areas (regional/sub-regional/local) or airports (e.g. snow situation), with variable granularity levels depending on the time horizon. (reference REQ-07.06.01-OSED-WX01.0010; source SESAR 1 OSED 07.06.01)'; 'To allow the Aircraft Operator or Ground Handler to set, update or delete the value of the Target Off-Block Time of a departing flight, in accordance with the operations involving Target Off-Block Time that take place between A-CDM Milestones 2 and 11 (derived from: Airport CDM Implementation Manual v4)'. Service functionality SWIM-SERV-012 A service description shall describe the functionality of the service as a list of functions and their associated real world effects. The functions provide business and operational experts with a business view of the interactions with the service, without having to look at the interface details. Verify that the elements are included. Verify that the functions and real world effects are consistent with the operational needs. Not Applicable. Note: A function is a type of activity describing the functionality of a service. Every function usually (but not always) can be mapped to service operations defined as a part of the service’s interface; i.e., functions provide a 'business view' and service operations provide a 'technical view' of a particular service activity. Note: A real world effect is an ultimate purpose associated with the interaction with the service. It may be the response to a request for information or the change in the state of some entities shared between the participants in the interaction. Example functions and real world effects: function$real world effect; Retrieve a list of flights $(Network Information sharing); Retrieve information of a single flight$(Network Information sharing); Provide Departure Planning Information (DPI)$NM systems updated with the information; NM systems publish the resulting flight update Service access and use conditions SWIM-SERV-013 A service description shall include the conditions which apply to accessing and using the service, such as legal constraint; service policies; service consumption constraints; and security constraints. This requirement ensures that a service consumer is aware of any limitations on the access and use of the service. It is good practice to share business constraint information associated with the conditions of usage of the service. Verify that the elements included cover the required constraints and policies. Not Applicable. Not Applicable. Example legal constraints: Licenses to be bought; Intellectual property rights to be respected. Example services policies: Contingency policy; Business policy(s) in terms of business rule or objective i.e. how the business is conducted; Operational policy(s) (i.e. constraints and requirements for how services operate and interoperate at runtime) in terms of rules and guidelines. Operational policies are utility centric (handling operational characteristics) covering mainly; , logging, messaging protocol and versioning. Normally standardised for a defined collection of services; Technical policy(s). Technical policies can (if available) be provided in machine-readable format; Versioning scheme used (e.g. major.minor[.fix]) and the compatibility guaranteed between different versions (e.g. backwards compatibility is guaranteed between minor versions but not for major); Lifecycle policy applied to the service (e.g. to allow consumers to know that he is not investing on a soon to be retired service). Example service consumption constraints: The maximum number of requests per time window allowed for a service consumer. Example security constraints: <TAB>Confidentiality: Statement of the confidentiality offered by the service (e.g. message, transport, none…); Elements of the payload whose confidentiality is required or provided (whole payload, body, specific sub-elements…); Cryptographic algorithms and key sizes; <TAB>Integrity: Statement of the integrity offered by the service (e.g. message, transport…); Elements of the payload whose integrity is required or provided (whole payload, body, specific sub-elements…); Cryptographic algorithms and key sizes; <TAB>Authentication: Statement of the authentication mechanisms used on consumer and provider side; Statement of the failed authentication constraints; Identity tokens; <TAB>Authorisation: Statement on the authorisation mechanism used; Credentials used for the authorisation; Levels of authorisation. Note: Additional use conditions could be diplomatic, geographical reasons, safety criticality and fees to be paid, for instance. Quality of service SWIM-SERV-014 A service description shall include statements on the quality of service offered with regards to: availability of the service; response time of the service; and throughput of the service. This is a key criterion in deciding to use the service. This is key information to be included in a service level agreement and will influence the content of the SLA. It informs contract negotiations between consumers and providers. Verify that quality statements are included in the service description. Not Applicable. Not Applicable. Note: The availability is typically expressed as a percentage representing the ratio between minimum target uptime versus maximum uptime. The service provider needs to describe the service outages he intends to mask/alleviate. The availability information needs to be expressed for various situations, e.g. planned and unplanned outages. The service provider needs to describe the schedule of planned outages. Example of availability: ≥ 99.95 % of Continuous Operations. Note: The response time expressing the delay to process a service request could include: delay in seconds, percentage of messages, message size. Example of response time: 2s delay for 95% of messages of average size 1MB, with no compression. Example of response time: max 3s response to complete a service request, measured from the time the service provider agent receives the request to the time the service provider transmits the response. Note: The throughput is typically expressed as a number of service requests that the service can accommodate within the given time period. Example of throughput: 200 service requests per minute. Note: It is a good practice to describe the measuring conditions of the quality of service figures given. Technical constraint SWIM-SERV-015 If technical constraints are known, a service description shall include information about the technical constraints that would guide the consumer in their client development. Knowing and satisfying the pre-requisite constraints of a service facilitate good use of the service, such as benefiting from the indicated quality of service statements. This requirement supports decision making in terms of assessing the implication, costs and feasibility, of using the service. Not Applicable. If provided, verify that the information corresponds to the described service. Not Applicable. Example technical constraints: firewall, minimum bandwidth or server resources, interface language, integration pattern, protocol and communication ports. Example: For a publication service where the subscription mechanism is not based on a capability of the service itself, stakeholders need to understand how they can subscribe (e.g. using electronic form, email, etc). Service interfaces SWIM-SERV-016 A service description shall list the service interfaces (provider side and consumer side interfaces), including for each service interface, the name of the service interface; a textual description of the service interface including its purpose; an indication that the interface is a provider side interface or a consumer side interface; and for a provider side interface, the fully qualified network address at which the interface can be accessed. This information facilitates the unambiguous identification of the interface, the understanding of its purpose, and the location to access it. Verify that the list of interfaces is included; verify that the name, description and indication are included for each interface. For each provider side interface, verify that the network address is provided. Not Applicable. Note: To improve readability across service descriptions, it is best practice to apply following conventions for a service interface name (the appendix B 'ISRM naming conventions' of the SESAR 1 Modelling Guidelines [RD 6] is a good source for naming conventions): be represented using UpperCamelCase; and use the <noun> <role> pattern where <noun> is a topic related to the service and <role> describes the roles in a composition/interaction sequence, based on the Message Exchange Pattern that is used. Example service interface names: FlightPlanCoordinator, FlightPlanSubmitter, ForecastProvider, ForecastConsumer, ClearanceRequester, ClearanceManager, PreDepartureSequencer, FlightInformationPublisher, AlertListener. Note: It is best practice to provide, in addition, the network address(es) for accessing the service instance(s) that can be used for testing and development purposes. Message exchange pattern SWIM-SERV-017 A service description shall include the message exchange pattern used by the service. The message exchange pattern helps understanding how the information interaction with the service works. Verify that the information is included. Verify that the information is consistent with the selected service interface binding. Not Applicable. Note: Typical message exchange patterns (as from the SWIM Technical Infrastructure Yellow Profile [RD 3]): Request/Reply (synchronous or asynchronous); Publish/Subscribe (Push or Pull); One Way (also known as Fire and Forget). SWIM TI Profile and interface bindings SWIM-SERV-018 A service description shall include for each service interface, the selected SWIM TI Profile and its version; a reference to a service interface binding as specified in the selected SWIM TI Profile; a reference to a network interface binding as specified in the selected SWIM TI Profile; and reference to additionally supported requirements as specified in the selected SWIM TI Profile. To support the concept of interoperability between the service provider and service consumer, the SWIM TI Profiles only allow a certain set of technical solutions, which can be chosen by the service designer. This is used by technical experts to assess feasibility to implement. Verify that the reference information is provided for each provider side and consumer side interface. Verify that the selected service interface binding, network interface binding and additionally supported requirements are consistent with the selected SWIM TI Profile and version. Not Applicable. Note: If configuration options are available in the service interface binding, it is best practice to document them (e.g. use of GZIP compression, Message Transmission Optimization Mechanism (MTOM) encoding). Example additionally supported requirements: 'SWIM-TIYP-0092, SWIM-TIYP-0098'. Service interface protocols and data format SWIM-SERV-019 A service description shall include the list of service interface protocols (including name and version) and data format to be used. Makes explicit within the service description what the protocols are. Verify that all relevant protocols and versions are listed; verify that the information is provided for each provider side and consumer side interface. Verify that the protocols are consistent with the selected interface binding. Not Applicable. 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). Machine-readable service interface definition SWIM-SERV-020 If the service interface binding specifies the use of machine-readable formats, a service description shall include or refer to a service interface definition in a machine-readable format using a standard service definition formalism/language. Enables consumer software components to be created. If the service interface binding supports it, verify that the required elements are included. Verify that provided elements are consistent with the selected binding. Not Applicable. Example machine-readable descriptions:<TAB>service descriptions: WSDL (e.g. if a Web Service binding using SOAP is selected); <TAB>message descriptions: XSD; Schematron Rules. Note: AMQP does not mandate a specific machine-readable format. Note: REST may use WSDL 2.0 or WADL. However, WADL is not standardised. Service operations SWIM-SERV-021 A service description shall include a technical description of the service operations of each of its interfaces, including: the name of the service operation; a description of the intent and the results of the service operation; and a description of the exchanged information by the service operation, including the input, output and error messages. The consumer needs to know which service operations are available to be called for the expected result. Verify that all service operations are described. Verify the service operations against the messaging technology needs. Not Applicable. Note: To improve readability across service descriptions, it is best practice to apply following conventions for a service operation name: include a verb and a noun; and be represented using lowerCamelCase. Example service operation names: getAlerts; requestTrajectoryAnalysis; publishAirportMETInducedCapacity; setCoordinationAndTransferData; proposeARESDeActivation. Note: For readability and understanding of services implemented using REST methods, it is best practice to define logical operations and to map these to the underlying REST methods being used. Note: In case of subscription in a Publish / Subscribe message exchange pattern, the management of subscriptions must be specified, including the use and management of subscription id, the mechanism to unsubscribe, etc. Note: When a service operation has several input parameters, it is best practice to indicate the role of each parameter. Note: It may be considered to include information such as the expected number of elements to be exchanged and their frequencies. Information definition SWIM-SERV-022 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. This requirement ensures that the precise meaning of the exchanged information is shared by all parties of the information exchange. Verify that the service description describes all elements of the exchanged information and that the required details are provided. Verify that the elements are consistent with each other and with the AIRM concepts used in the semantic correspondence. Not Applicable. 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]. AIRM conformance SWIM-SERV-023 A service description shall include a statement indicating whether the information definition used by the service conforms to the ATM Information Reference Model (AIRM); and if so, the version of the AIRM to which it conforms. To achieve semantic interoperability. Verify that the conformance statement is present. If the statement claims conformance with the AIRM, verify that the AIRM version is included. Verify that the statement is true. Example AIRM conformance statements: 'Conformant with AIRM version 4.1.0'; 'Not conformant with AIRM' Filter capabilities SWIM-SERV-024 A service description shall describe the filtering capabilities, including meaning and syntax of filter expressions, which can be applied to the information exchange. This requirement ensures that the precise meaning of the filter expressions is understood. If filter expressions are applied, verify that the capabilities, meaning and syntax are included. Not Applicable. Not Applicable. Examples include indication of how to interpret and/or combine filters, including cases such as usage of wildcards, allowing and interpreting empty filters, combinations of filters in terms of logical expressions (e.g. implicit AND, implicit OR, explicit operator), etc. Note: Nothing needs to be provided when the exchanged information has no filter expression. Service behaviour SWIM-SERV-025 A service description shall include information on the behaviour of the service including: the sequence of service operations; and the handling of unexpected behaviour. This requirement facilitates the understanding of the service behaviour, including the sequencing of service operations to support operational processes, and the error handling. Verify that the behaviour information is included and covers the errors handling as well. Verify that the names of the interfaces, service operations and exchanged information are consistent with the interface definitions. Not Applicable. Examples of behaviour specification: The behaviour under normal conditions; The behaviour with incorrect input data (e.g., out of range or incorrect data type); The use of error messages, and error handling in general; The list of error codes and expected effects. Note: The service behaviour can be captured in formal modelling notations such as a Unified Modeling Language (UML) sequence diagram, and/or expressed as textual description in plain language. Model view SWIM-SERV-026 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. 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. 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. If the model view is provided, verify that the model view is consistent with the service description (e.g. same service operation name). If the model view is provided, verify that the model view is aligned with the declared notation. 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]. Service validation SWIM-SERV-027 A service description shall include a statement indicating whether a validation of the service has been performed; and if so, the method used and the results achieved. This requirement ensures the service description contains sufficient statements on the testing done to enable the consumer to have confidence in the quality of the service. Verify that the validation statement is included. If validation has been performed, verify that the statement includes the method and the results of the validation. Not Applicable. Example service validation statement: 'The service has not been validated yet'. Service monitoring SWIM-SERV-028 If a service monitoring mechanism is available to service consumers, a service description shall describe how to use the service monitoring mechanism. Allow the service consumer to use the available mechanism and monitor the service. If a service monitoring mechanism is available, verify that the information is included. Not Applicable. Not Applicable. Examples: Monitoring the availability of the service (e.g. by heartbeat); monitoring response time. Examples of code SWIM-SERV-029 A service description should include or refer to examples of code exemplifying the implementation of the consuming interface. Best practice to speed up prototyping. Not Applicable. If provided, verify that the provided examples correspond to the described service. Not Applicable. Examples include source code in a given programming language, input and output messages.