Working towards the next version of the SWIM Supporting Material

Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Excerpt

Guidance starting from the schema structure


Object under assessment

JSON Schema 0.0.3, as used by the SWIM Registry application for uploading / downloading Registry Entries. 

Legend

Expand
titleLegend [+]
Rows

each row represents an attribute or a type of the schema

    attributes are in white background

    types are in light blue background

the rows are in "logical" order for types and attributes, in order to facilitate the walk through 

    this order could become standard practice for JSON service descriptions


Columns1st = row number



1/ derived from the schema

col = name of the type

col =  name of the attribute (or "---" when not an attribute)

col = description of the element (type or attribute)

col = type of the attribute (or "---" when not an attribute)



2/ "guidance"

col = trace and link to the requirement(s)

col = guideline to help in using this type / attribute



3/ "rule"

col = rule for COMPLIANT case

col L = rule for CANDIDATE case 

col M = rule for DEFINITION case 

     "same" means the compliant rule applies 
Panel
borderColorlightgrey

Table of Contents

Walk-through

Schema elements

Lists all elements (attributes and types). Except for the enumerated values which are in Code Lists walk-through or in related requirement.

1Element NameAttribute NameDescriptionAttribute TypeRequirement infoGuidelineCOMP RuleCAND ruleDEFN Rule
2---informationServiceThe description of a service.[SWIM-SERV-001]InformationServiceSWIM-SERV-001 Description coverageRationale: The readability of a service description is improved by keeping it focussed on one service.Mandatorysamesame
3InformationService---A type of service that provides an ATM information sharing capability.---SWIM-SERV-001 Description coverageGuidance: Describe here your prospective service, operational service or service definition.(M)samesame
4InformationServicedescriptionInformationA container for Service Description metadata.DescriptionInformationmultipleNote: This information is about the document  more than the underlying service.Mandatorysamesame
5InformationServicenameA piece of identifying information that gives stakeholders a way to reference or identify a service. [SWIM-SERV-006]stringSWIM-SERV-006 Service identificationThe name of the information service providing consumers the ability to reference or identify an information service through a name that gives an indication of the purpose of the information service. Guidance: Include only the name of the service.Mandatory, minLength=1samesame
6InformationServiceversionThe version of the information service. [SWIM-SERV-006]stringSWIM-SERV-006 Service identificationStructured description of the information service version; enabling consumers to distinguish between releases of the service. Guidance: An indicator of version is always provided regardless of whether or not there are multiple versions of a service. Each version of a service shall have its own completed description.Mandatory, minLength=1samesame
7InformationServiceserviceAbstractA brief summary of the service offering. [SWIM-SERV-007]stringSWIM-SERV-007 Service abstract

Rationale: This information supports the decisions on whether the described service is suitable for use in a particular situation.

Guidance: Include or introduce:

  • the operational need being addressed by the service
  • the intended use of the service
  • the intended consumer audience for the service
  • the geographical extent

For a new version of a service, consider mentioning the service's first date of operation. Eg "XXX service is in operation since yyyy-mm-dd".

Mandatory, minLength=5samesame
8InformationServiceserviceProvisionA container for information about who provides the service, when and how it is supported.ServiceProvisionSWIM-SERV-008 Service providerRationale: Knowing the service provider is essential to business experts.
Rationale: Point of contact allows getting additional information regarding the service.
Mandatorysame Optional if providerType moved outside
9InformationServiceserviceCategorisationA taxonomy used to classify a service by the type of service provided or by some other technological or architectural solution. [SWIM-SERV-009]ServiceCategorisation

SWIM-SERV-009 Service categories

SWIM-REG-0004 Service categorization

Rationale: Service category information allows discovering services by a series of classification criteria. Mandatorysamesame
10InformationServiceserviceGeneralDescriptionA container for information about what the service provides, its purpose and under which conditions and quality levels it is provided.ServiceGeneralDescriptionmultiple
Mandatorysamesame
11InformationServiceserviceInformationDescriptionA container for the description of the information exchanged by the information service.ServiceInformationDescriptionmultipleRationale: Provide a description of the information/data that is exchanged by the service.MandatoryMandatoryMandatory
12InformationServiceserviceTechnicalDescriptionA container for information about the security mechanisms, technical constraints and monitoring of the information service.ServiceTechnicalDescriptionmultipleNote: the attribute is mandatory, so that authors consider the underlying Mandatory Conditional information.Mandatory

13InformationServiceserviceInterfaceThe means by which the underlying capabilities of a service are accessed.Interfacemultiple

Guidance: Describe one or more interfaces.

Provide all interfaces: provider side and consumer side interfaces.

Mandatory, minItems=1

14InformationServiceserviceDescriptionReferencesA container for references to documents describing specific aspects of the service instance.ServiceDescriptionReferencesmultiple
Mandatory

15DescriptionInformation---Information identifying the service description.---multipleNote: This groups information specific to the service description, and not about the underlying service.(M)samesame
16DescriptionInformationserviceDescriptionIdentificationInformation identifying the service description.ServiceDescriptionSWIM-SERV-005 Description identification
Mandatorysamesame
17DescriptionInformationabbreviationsAbbreviations or acronyms used by the service description.AbbreviationSWIM-SERV-003 Define abbreviationsGuidance: Define all abbreviations and acronyms used in the description. Unless they are systematically made explicit, such as in "IFR (Instrument Flight Rules)".Mandatory, minItems=0samesame
18ServiceDescription---Information needed in order to use, or consider using, a service.---SWIM-SERV-005 Description identificationRationale: supports the identification and citation of a service description.(M)samesame
19ServiceDescriptionserviceDescriptionTitleThe name by which the document is formally known. [SWIM-SERV-005;SWIM-SERV-010]stringSWIM-SERV-005 Description identification
Mandatory, minLength=5samesame
20ServiceDescriptionserviceDescriptionEditionManifestations of a publication embodying essentially the same content. [SWIM-SERV-005]stringSWIM-SERV-005 Description identificationNote: 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.Mandatory, minLength=1samesame
21ServiceDescriptionserviceDescription ReferenceDateThe date at which the document has been published. [SWIM-SERV-005]stringSWIM-SERV-005 Description identification
Mandatory, format is "yyyy-mm-dd"samesame
22Abbreviation---An abbreviation or acronym used by the service description. [SWIM-SERV-003]---SWIM-SERV-003 Define abbreviations

Guidance: Be in accordance with the AIRM abbreviation list. It is allowed to use abbreviations/acronyms not defined in AIRM abbreviation list. However, when using one of those, their definitions must be the same.

(M)samesame
23AbbreviationnameThe name of the abbreviation. [SWIM-SERV-003]stringSWIM-SERV-003 Define abbreviations

The abbreviated form eg "IFR".

Verification: Check if the abbreviation exists in AIRM, verify the term is the same.

Mandatory, minLength=1samesame
24AbbreviationdescriptionThe description of the abbreviation.stringSWIM-SERV-003 Define abbreviationsThe term in full lenth eg "Instrument Flight Rules". Verification: Check if the term exists in AIRM and is abbreviated, verify the abbreviation is the same.Mandatory, minLength=5samesame
25ServiceProvision---Description of who provides the service, when and how it is supported.---SWIM-SERV-008 Service provider
(M)

26ServiceProvisionproviderThe full official name of the organisation. [SWIM-SERV-008]stringSWIM-SERV-008 Service providerRationale: Knowing the service provider is essential to business experts.Mandatory, minLength=1

27ServiceProvisionproviderDescriptionDescription of the organisational unit responsible for the service. [SWIM-SERV-008]stringSWIM-SERV-008 Service provider

Guidance: Provide a small description of the organisation and/or the unit responsible for the service

Consider including information on provider certification when relevant for the service being described (e.g. for a Meteorological service).

Mandatory, minLength=5

28ServiceProvisionproviderTypeThe type of service provider.CodeStakeholderType

SWIM-SERV-009 Service categories



Mandatory, minItems=1

29ServiceProvisiondateInOperationDate at which the service went into operation or is planned to become operational.stringSvcOvw

Provide the date at which this service version became operational.

Note: The date at which the service became operational for the first time may be mentioned in the service abstract.

Mandatory, format is "yyyy-mm-dd"

30ServiceProvisionserviceSupportProvision of material and guidance necessary for the use of the information service.stringSvcOvw

Specify days and hours the information service provider can be contacted by users requiring support for the provided service.

Rationale: A description of the support a provider is offering to consumers on all relevant aspects related to the information service. Rationale: Consumer needs will vary and may require different levels of provider support.

Optional
same
31ServiceProvisionpointOfContactA person or group within the service provider organization, suitable for making a human contact for any purpose. [SWIM-SERV-008]PointOfContactSWIM-SERV-008 Service providerProvide one or more points of contact where additional information can be obtained, including name, contact information and role.Mandatory, minItems=1

32PointOfContact---A person or group within an organization, suitable for making a human contact for any purpose. [SWIM-SERV-008]---SWIM-SERV-008 Service providerGuidance: At least one contact information is required. 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”.
(M)

33PointOfContactnameThe name of the point of contact.stringSWIM-SERV-008 Service provider
Mandatory, minLength=1

34PointOfContactdescriptionThe description of the point of contact.stringSWIM-SERV-008 Service providerDescribe the role / function of the point of contact. When applicable add contact info such as URL link or postal address.Mandatory, minLength=5

35PointOfContactemailAn electronic mail address used to correspond in writing with the point of contact.stringSWIM-SERV-008 Service providerGuidance: At least one contact information is required.Optional

36PointOfContactphoneNumberA telephone number used to communicate orally with the point of contact.stringSWIM-SERV-008 Service providerGuidance: At least one contact information is required.Optional

37ServiceCategorisation---A taxonomy used to classify a service by the type of service provided or by some other technological or architectural solution. [SWIM-SERV-009]---SWIM-SERV-009 Service categoriesRationale: Service category information allows discovering services by a series of classification criteria. (M)samesame
38ServiceCategorisationserviceTypeAn indication of the status of the service with regard to SWIM Service conformance.CodeSWIMService ConformanceStatusType

SWIM-REG-0004 Service categorization

Guidance: Select a code as indicated in Code Lists walk-through.

Mandatory, value= SWIM_COMPLIANT

same, value= SWIM_CANDIDATEsame, value= DEFINITION
39ServiceCategorisationlifeCycleStageA classification of services based on their current, past, or future availability for provisioning. [SWIM-SERV-009]CodeLifeCycleStepType

SWIM-REG-0004 Service categorization

This is the life-cycle stage of a service instance. Use OPERATIONAL if already operational, either use PROSPECTIVE. Don't put any value for a DEFN.Mandatory; value= OPERATIONAL
(absent)
40ServiceCategorisationbusinessActivityTypeThe type of business activity.CodeBusinessActivityType

SWIM-REG-0004 Service categorization

Select one or more code valuesMandatory, minItems=1

41ServiceCategorisationintendedConsumerThe types of service consumers that this service is intended to serve.CodeStakeholderType

SWIM-REG-0004 Service categorization

Select one or more code values

Note: list the "intended" consumer audience from your point of view. This does not mean that consumers outside that list wouldn't benefit from the service.

Mandatory, minItems=1

42ServiceCategorisationinformationCategoryTBDCodeInformationExchangeCategory

SWIM-SERV-009 Service categories

Select one or more code valuesMandatory, minItems=1

43ServiceCategorisationapplication MessageExchangePatternThe type of Application MEP. [SWIM-SERV-017]CodeApplication MessageExchangePatternType

SWIM-SERV-017 Message exchange pattern

Select one or more code values.

Message exchange pattern at application level. Typical values are: Request/Reply (synchronous or asynchronous); Publish/Subscribe (Push or Pull);
One Way. See as well doc xxx (see handbook).

Mandatory, minItems=1

44ServiceCategorisationgeospatialCategorisationThe geographic coverage of the information provided by the service. [SWIM-SERV-009]GeographicalExtent

SWIM-REG-0004 Service categorization

Rationale: Allow consumer to understand and search on the geographical coverage of the service.

Guidance: Consider summarising it in the service abstract as well.

Optional

45GeographicalExtent---The geographic coverage of the information provided by the service.---

SWIM-REG-0004 Service categorization

SERV-OVW-008 Geographical extent

Guidance: Geographical coverage may be expressed in terms of ICAO state, FIR, Aerodrome.

Rationale: Allow consumer to understand the geographical coverage of the service.

(O)samesame
46GeographicalExtentstateICAONationalityLettersNationality letters of a State as defined by ICAO. [SWIM-SERV-009]string

SWIM-REG-0004 Service categorization

List zero or more code values.
  Applicable
  Applicable values are in ICAO doc 7910.Optionalsamesame
47GeographicalExtentfirICAOLocationIndicatorA four-letter code group formulated in accordance with rules prescribed by ICAO and assigned to the airspace. [SWIM-SERV-009]string

SWIM-REG-0004 Service categorization

List zero or more code values.
  Applicable
  Applicable values are in ICAO doc 7030.Optionalsamesame
48GeographicalExtentaerodrome ICAOLocationIndicatorA four-letter code group formulated in accordance with rules prescribed by ICAO and assigned to the aerodrome. [SWIM-SERV-009]string

SWIM-REG-0004 Service categorization

List zero or more code values.
  Applicable
  Applicable values are in ICAO doc 7910.Optionalsamesame
49ServiceGeneralDescription---Description of the service in terms of what it provides, the purpose and under which conditions and quality levels the service is provided.---multiple
(M)samesame
50ServiceGeneralDescriptionoperationalNeedThe operational need fulfilled by the service [SWIM-SERV-011]OperationalNeedSWIM-SERV-011 Operational needs

List the operational needs such as operational context and requirements that are at the origin of the service.

Rationale: 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 information supports decision making in terms of service suitability within a particular operational context.

Mandatory, minItems=1samesame
51ServiceGeneralDescriptionfunctionalityA type of activity describing the functionality of a service. [SWIM-SERV-012]FunctionalitySWIM-SERV-012 Service functionality

Express the functionality offered by the service as a list of service functions.

Rationale: 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.

Mandatory, minItems=1samesame
52ServiceGeneralDescriptionaccessAndUseConditionA condition which applies to accessing and using the service, such as legal constraint, service policies, service consumption constraints and security constraints. [SWIM-SERV-013]AccessAndUseConditionSWIM-SERV-013 Access and use conditions

List the conditions that apply to access or use the service.

Rationale: 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.

Mandatory, minItems=1

53ServiceGeneralDescriptionqualityOfServiceThe degree or level of confidence that the performance of a service meets users requirements. [SWIM-SERV-014]QualityOfServiceSWIM-SERV-014 Quality of service

Guidance: Include at least statements on the quality of service offered with regards to availability, response time and throughput of the service.

Rationale: 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.

Mandatory, minItems=3

54ServiceGeneralDescriptionconceptsOptional information intended for a good understanding of the service. This may cover design concepts related to the service, logical model, design considerations, or any other information not pertaining to the other fields.Concept

SWIM-SERV-ADD Additional info

SWIM-SERV-024 Filter capabilities

SERV-OVW-008 Geographical extent        

SERV-OVW-017 Sources of information

List additional information deemed useful for a good use of the service.

Use as well for pre-defined uses such as, for instance, Filter capabilities or Sources of information.

The Concept type covers some predefined uses as well. Each predefined use is related to a requirement, and proposes a value for the "name" field (which would allow automatic processing).



Optional, minItems=0samesame
55ServiceGeneralDescriptionvalidationActivity whereby a service is checked for conformance with the service objectives and requirements. [SWIM-SERV-027]ValidationOfServiceSWIM-SERV-027 Service validationList one or more validation activities.Mandatory, minItems=1Optional
56OperationalNeed---A statement of the operational attributes of a system needed for the effective and/or efficient provision of air traffic services to users. [SWIM-SERV-011]---SWIM-SERV-011 Operational needs

This requirement supports decision making in terms of service suitability within a particular operational context.

Guidance:

  • 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).
  • indicate relationship to PCP and/or SESAR Deployment Plan

Rationale: 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.

(M)samesame
57OperationalNeednameThe name of the operational requirement.stringSWIM-SERV-011 Operational needsGuidance: provide a short name for the operational needMandatory, minLength=1samesame
58OperationalNeeddescriptionDescription of the operational needs fulfilled by the service. Includes or refers to information exchange requirements [SWIM-SERV-011].stringSWIM-SERV-011 Operational needs

Describe the operational context of the service. And make reference to the ConOps, OSED or other applicable reference document where additional information on the operational concept can be found.

Make explicit the needs addressed by the service.

List the requirements at the origin of the service (eg IERs).

Mandatory, minLength=5samesame
59Functionality---A type of activity describing the functionality of a service.---SWIM-SERV-012 Service functionality




(M)samesame
60FunctionalitynameThe name of the service function.stringSWIM-SERV-012 Service functionalityProvide a short name for the service functionMandatory, minLength=1samesame
61FunctionalitydescriptionDescription of the service function. [SWIM-SERV-012]stringSWIM-SERV-012 Service functionality

Describe here the service function.

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.

Mandatory, minLength=5samesame
62FunctionalityrealWorldEffectAn 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. [SWIM-SERV-012]stringSWIM-SERV-012 Service functionality

Describe here the real-world-effect, if any.

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.

Mandatory, minLength=0samesame
63AccessAndUseCondition---A condition which applies to accessing and using the service, such as legal constraint, service policies, service consumption constraints and security constraints. [SWIM-SERV-011]---SWIM-SERV-013 Access and use conditions
(M)

64AccessAndUseConditiontypeThe type of service access or use condition. [SWIM-SERV-013]CodeAccessAndUseConditionTypeSWIM-SERV-013 Access and use conditionsSelect the code value indicating the type of condition: LEGAL CONSTRAINT , SERVICE POLICY, SERVICE CONSUMPTION CONSTRAINT, SECURITY CONSTRAINT, OTHER.Mandatory

65AccessAndUseConditionnameThe name of the condition.stringSWIM-SERV-013 Access and use conditionsProvide a short name for the condition.Mandatory, minLength=
5
1

66AccessAndUseConditiondescriptionDescription of the conditions that influence accessing and using the service, such as legal constraint; service policies; service consumption constraints (SWIM-SERV-013). Concrete access control and other security mechanisms are described in the technical section of the form.stringSWIM-SERV-013 Access and use conditions

Describe the conditions which apply to accessing and using the service, so that the consumer is aware of any limitations on the access and use of the service.

Note: the SD spec includes examples of such conditions.

Note: Concrete access control and other security mechanisms are described in the technical section of the form (see SecurityMechanism)

Mandatory, minLength=5

67QualityOfService---The degree or level of confidence that the performance of a service meets users requirements.---SWIM-SERV-014 Quality of service
(M)

68QualityOfServicenameThe name of the quality of service. [SWIM-SERV-014]stringSWIM-SERV-014 Quality of service

Provide a clear and concise name for the quality of service, such as "Availability", "Response time", "Throughput".

Consider as well describing less quantitative aspects such as "Integrity", "Confidentiality" and other service related qualities defined in ISO 25010

Mandatory, minLength=
5
1

69QualityOfServicedescriptionDescription of the quality of service offered with regards to: 1)availability of the service; 2)response time of the service; and 3)throughput of the service (SWIM-SERV-014). It also describes less quantitative aspects suchs as 4)integrity, 5)confidentiality and possibly any other service related qualities defined in ISO 25010stringSWIM-SERV-014 Quality of serviceSee Notes / Examples of the requirement.Mandatory, minLength=5

70Concept---Optional information intended for a good understanding of the service. This may cover design concepts related to the service, logical model, design considerations, or any other information not pertaining to the other fields.---

SWIM-SERV-ADD Additional info

SWIM-SERV-024 Filter capabilities

SERV-OVW-008 Geographical extent   

SERV-OVW-017 Sources of information    

Include useful information that could not fit nicely in another section.

Use as well to cope with shortcomings of the schema. Eg Filter capabilities.

Rationale: The requirements prescribe the minimum set of elements to be contained by a service description. Additional information useful for a good use of the service should be made available.

(O)samesame
71ConceptnameThe name of the concept.string

SWIM-SERV-ADD Additional info

Guidance: Define a name that makes clear what the description is about.

For -predefine use, use the name as defined below precisely (which would allow automatic processing):

Mandatory, minLength=
5
1

72ConceptdescriptionDescription of the concept.string

SWIM-SERV-ADD Additional info

Provide the description.Mandatory, minLength=5

73ValidationOfService---An activity whereby a service is checked for conformance with the service objectives and requirements. Note: the service objectives and requirements are captured in the service overview and the technical specifications. [SWIM-SERV-027]---SWIM-SERV-027 Service validation

Indicate whether a validation of the service has been performed; and if so, the method used; and the results achieved.

Rationale: User needs to know how the information service was validated in order to have confidence in the service.

(M)

74ValidationOfServicetypeThe type of service validation. [SWIM-SERV-027]CodeServiceValidationType

SvcOvw

SWIM-SERV-027 Service validation

Select the code value corresponding to the validation method used, (User Validated, Self-Validation, Collaborative, or Independent)

Note: Is mandatory except for the case not validated.

Optional

75ValidationOfServicedescriptionThe description of the service validation. [SWIM-SERV-027]stringSWIM-SERV-027 Service validation

Include a brief statement on the validation results, and if/how the potential consumers may obtain the validation evidence.

Example: This information service has undergone extensive testing prior to deployment by the information service provider “LMN”, infrastructure service provider “ABC”, and regulator “XYZ” to ensure that specific QoS standards are met. Operational monitoring by the information service provider is in place and the information service continues to meet all QoS requirements. For more information on this organization’s validation policies please see <URL>. Specific information regarding the validation by the regulator is available in a validation report upon request.

Mandatory

76ServiceInformationDescription---A container for the description of the information exchanged by the information service.---multiple

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

Guidance: SWIM-SERV-022 Information definition 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)(M)(M)
77ServiceInformationDescriptioninformationDefinitionA formal representation of information concepts or data concepts. [SWIM-SERV-022]InformationDefinitionSWIM-SERV-022 Information definitionRationale: Enables to understand the information provided by the service, with a specific focus to the semantics of the informationMandatory, minItems=1MandatoryMandatory
78ServiceInformationDescriptionexchangeSchemaFormal description of the data involved in an information exchange.ExchangeSchemaSWIM-SERV-019 Protocols and data format

List the data formats used.

Mandatory, minItems=1OptionalOptional
79InformationDefinition---A formal representation of information concepts or data concepts. [SWIM-SERV-022]---SWIM-SERV-022 Information definitionRationale: Enables to understand the information provided by the service, with a specific focus to the semantics of the information(M)(M)(M)
80InformationDefinitionnameThe name of the Information Definition. [SWIM-SERV-022]stringSWIM-SERV-022 Information definitionGuidance: 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, minLength=1MandatoryMandatory
81InformationDefinitiondescriptionThe description of the Information Definition. [SWIM-SERV-022]stringSWIM-SERV-022 Information definition

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, minLength=5OptionalOptional
82InformationDefinitionairmConformantAn indication whether the information definition used by the service conforms to the ATM Information Reference Model. [SWIM-SERV-023]booleanSWIM-SERV-023 AIRM conformance

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


MandatoryMandatoryMandatory
83InformationDefinitionairmVersionThe applicable version of the ATM Information Reference Model. [SWIM-SERV-023]stringSWIM-SERV-023 AIRM conformance

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 MandatoryOptionalsame
84ExchangeSchema---Formal description of the data involved in an information exchange.---SWIM-SERV-019 Protocols and data formatRationale: Enables to understand data format(s).(M)(M)(O)
85ExchangeSchemanameThe name of the exchange schema. [SWIM-SERV-019]stringSWIM-SERV-019 Protocols and data formatGuidance: Provide the name of the data format that is used to exchange data via the service interface.MandatoryMandatoryMandatory
86ExchangeSchemaschemaLanguageDescription of the language used (e.g. XML, JSON). [SWIM-SERV-019]stringSWIM-SERV-019 Protocols and data formatGuidance: Indicate the language in which the data format is expressed (e.g. XSD, JSON, natural language,..)MandatoryOptionalOptional
87ExchangeSchemareferenceA reference to the exchange schema containing the specifications of the data structures.stringSWIM-SERV-019 Protocols and data formatGuidance: Indicate with a reference the location of where the data format is defined (e.g. See service documents)OptionalOptionalOptional
88ServiceTechnicalDescription---Description of the technical aspects of the service including data structures, interface and operations behaviour, security mechanisms and technical constraints---multipleNote: It may be possible that this results in an empty object.(M)

89ServiceTechnicalDescriptiontechnicalConstraintA characteristic of the environment or larger system within which the service operates. [SWIM-SERV-015]TechnicalConstraintSWIM-SERV-015 Technical constraint

Rationale: 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.It also supports decision making in terms of assessing the implication, costs and feasibility, of using the service.

Guidance: When technical constraints exist, it is mandatory to describe them.

Guidance: Describe zero or more technical constraints.

Optional, minItems=0samesame
90ServiceTechnicalDescriptionsecurityMechanismA process (or a device incorporating such a process) that is utilized or implemented by the service in order to address a security threat.SecurityMechanismSWIM-SERV-019 Protocols and data format

Guidance:  list the (security protocols) that are global for the service, if any.

Note: In Interface.interfaceBindingDescription list per interface the protocols not already mentioned here.

Optional, minItems=0

91ServiceTechnicalDescriptionserviceMonitoringA service monitoring mechanism available to service consumers. [SWIM-SERV-028]ServiceMonitoringSWIM-SERV-028 Service monitoring

Guidance: When such a mechanism is made available to consumers, it is mandatory to describe it.

Rationale: Allow the service consumer to use the available mechanism and monitor the service.

Conditional
Mandaotry
MandatoryOptionalOptional
92SecurityMechanism---A process (or a device incorporating such a process) that is utilized or implemented by the service in order to address a security threat.---SWIM-SERV-019 Protocols and data format

Guidance: (security mechanism) protocol valid for the service.

See as well Interface.interfaceBindingDescription

(M)

93SecurityMechanismnameThe name of the security mechanism.stringSWIM-SERV-019 Protocols and data format

Provide the name and version of the protocol.

Eg X.509v3 Client Certificate

Mandatory

94SecurityMechanismdescriptionThe description of the security mechanism.stringSWIM-SERV-019 Protocols and data format

Describe the mechanism

Eg Authentication performed based on  X.509 client certificates over a secured connection based on TLS.

Mandatory

95SecurityMechanismtypeThe type of security mechanism.CodeSecurityMechanismTypeSWIM-SERV-019 Protocols and data format
Select zero or more code values that indicate the type of security mechanism.
Mandatory
Optional, minItems=0

96TechnicalConstraint---A characteristic of the environment or larger system within which the service operates. [SWIM-SERV-015]---SWIM-SERV-015 Technical constraint

Note: Mandatory when existing.

Example technical constraints: firewall, minimum bandwidth or server resources, interface language, integration pattern, protocol and communication ports.

(O)samesame
97TechnicalConstraintnameThe name of the technical constraint. [SWIM-SERV-015]stringSWIM-SERV-015 Technical constraintGuidance: Provide a concise name for the technical constraint.Mandatory, minLength=1

98TechnicalConstraintdescriptionThe description of the technical constraint. [SWIM-SERV-015]stringSWIM-SERV-015 Technical constraintGuidance: describe the technical constraint.Mandatory, minLength=5

99ServiceMonitoring---Tracking state and operational conditions related to the execution, performance, and real-world effects of services.---SWIM-SERV-028 Service monitoringNote: Mandatory when available.(O)samesame
100ServiceMonitoringmonitoringDescriptionDescription if available of the existing monitoring capabilities and how this can be used by the consumer. [SWIM-SERV-028].stringSWIM-SERV-028 Service monitoringGuidance: provide the description so that the mechanism can be used by the consumer.Mandatory, minLength=5

101Interface---The means by which the underlying capabilities of a service are accessed. [SWIM-SERV-016]---SWIM-SERV-016 Service interfaces

Rationale: This information facilitates the unambiguous identification of the interface, the understanding of its purpose, and the location to access it.

(M)

102InterfacenameThe name of the interface. [SWIM-SERV-016]stringSWIM-SERV-016 Service interfaces
Mandatory, minLength=1

103InterfacedescriptionThe description of the entity. [SWIM-SERV-016]stringSWIM-SERV-016 Service interfacesGuidance: a textual description of the service interface including its purpose.Mandatory, minLength=5

104InterfaceinterfaceProvisionSideAn indication that the interface is a provider side interface or a consumer side interface. [SWIM-SERV-016]CodeInterfaceSideTypeSWIM-SERV-016 Service interfacesGuidance: select the appropriate value.Mandatory

105InterfacetiPrimitive MessageExchangePatternThe type of primitive MEP implemented by the interface.CodePrimitive MessageExchangePatternTypeN/A

Rationale: makes explicit the MEP used by the operations within this interface.

Guidance: select the appropriate value.

Mandatory

106InterfaceserviceInterfaceBindingAn interface binding that enables services to exchange data with consuming applications. [SWIM-SERV-018]CodeServiceInterfaceBindingTypeSWIM-SERV-018 TI Profile and bindings

Rationale: 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.

Guidance: select the appropriate code value.

Note: the code value also indicates the TI profile and version.

Mandatory

107InterfacenetworkInterfaceBindingAn interface binding that enables the SWIM TI to exchange data with the network. [SWIM-SERV-018]CodeNetworkInterfaceBindingTypeSWIM-SERV-018 TI Profile and bindingsGuidance: select the appropriate code value.Mandatory

108InterfaceinterfaceBindingDescriptionComplementary description of the protocols and other specifications used by the interface complementing the selected bindings, or any additional requirement specified in a SWIM TI Profile that is supported by the interface. [SWIM-SERV-018], [SWIM-SERV-019]string

SWIM-SERV-018 TI Profile and bindings

SWIM-SERV-019 Protocols and data format

Rationale: Makes explicit within the service description what the protocols are.

Guidance: Provide here a textual description of

  • additionally supported requirements as specified in the selected SWIM TI Profile
  • list of service interface protocols (including name and version), except for the protocols already mentioned in securityMechanism.
Mandatory, minLength=
5
1

109InterfaceendPointLocation at which information is received to invoke and configure interaction. [SWIM-SERV-016]EndPointSWIM-SERV-016 Service interfaces

Rationale: This information facilitates the the understanding of the location to access the interface.

Guidance: Provide the end point to be used for operational purpose. It is best practice to provide, in addition, the endpoint that can be used for testing and development purposes.

Mandatory, minItems=1

110InterfaceoperationSpecification of a transformation or query that an object may be called to execute. [SWIM-SERV-021]OperationSWIM-SERV-021 Service operations

Rationale: The consumer needs to know which service operations are available to be called for the expected result.

Guidance: describe all service operations of the interface (one or more operations).

Mandatory, minItems=1

111InterfacebehaviourThe manner in which a service operates under normal and unexpected conditions. [SWIM-SERV-025]ServiceBehaviourSWIM-SERV-025 Service behaviour

Rationale: This requirement facilitates the understanding of the service behaviour, including the sequencing of service operations to support operational processes, and the error handling. 

Guidance: provide one or more behaviours.

Note: The behaviour description may refer to a SERVICE_BEHAVIOUR_DESCRIPTION document.

Note:

Behaviour

Behaviour often concerns closely related operations in the same interface. Would behaviour relate operations from different interface, feel free to describe it in one of the concerned interface.

Mandatory, minItems=1

112EndPoint---Location at which information is received to invoke and configure interaction.---SWIM-SERV-016 Service interfacesRationale: This information facilitates the the understanding of the location to access the interface.(M)(O)NA
113EndPointnameThe name of the end point.stringSWIM-SERV-016 Service interfaces

Guidance: Provide a concise name that makes clear the usage of the end-point. Example: "Operational", "Pre-operational evaluation".

MandatoryMandatoryNA
114EndPointdescriptionThe description of the entity.stringSWIM-SERV-016 Service interfacesGuidance: If useful, provide additional information on the end-point, such as usage, accessibility, etc.OptionalOptionalNA
115EndPointaddressA network-visible identifier used to designate specific endpoints in a network. [SWIM-SERV-016]stringSWIM-SERV-016 Service interfacesGuidance: provide the fully qualified network address at which the interface can be accessedMandatoryOptionalNA
116EndPointaddressableResourceA resource that can be addressed through this End Point.ResourceN/A

Guidance: consider providing additional information describe the resource that is made available at the endpoint for the consumer to better understand the connection and exchanges with the endpoint.

E.g. An endpoint that provides a QUEUE as a resource, can be further described to explain its behaviour e.g. FIFO, LIFO.

E.g. An endpoint that provides a REST-RESOURCE indicates the architecture of the service, and the fact that the endpoint can have multiple resources it enables to list all the REST resources available under an endpoint for which all operations of the interface apply (typical of REST architecture)

OptionalOptionalNA
117Resource---Anything that can have an identifier. Although resources in general can be anything, SWIM is only concerned with those resources that are relevant to information services and therefore have some additional characteristics. In particular, they incorporate the concepts of ownership and control: a resource that appears in SWIM is a thing that has a name, may have reasonable representations and which can be said to be owned. The ownership of a resource is critically connected with the right to set policy on the resource.---N/A

Guidance: consider providing additional information describe the resource that is made available at the endpoint for the consumer to better understand the connection and exchanges with the endpoint.

E.g. An endpoint that provides a QUEUE as a resource, can be further described to explain its behaviour e.g. FIFO, LIFO,.

E.g. An endpoint that provides a REST-RESOURCE indicates the architecture of the service, and the fact that the endpoint can have multiple resources it enables to list all the REST resources available under an endpoint for which all operations of the interface apply (typical of REST architecture)

(O)(O)NA
118ResourcetypeThe type of resource.CodeTechnicalResourceTypeN/ARationale: Indicates the type of the resource: QUEUE, TOPIC,..OptionalOptionalNA
119ResourcenameThe name of the resource.stringN/AGuidance: provide a self descriptive nameMandatory, minLength=1MandatoryNA
120ResourcedescriptionThe description of the resource.stringN/AGuidance: Consider providing additional information that enables to understand the resource ( E.g. For QUEUE the behavior FIFO)OptionalOptionalNA
121Operation---Specification of a transformation or query that an object may be called to execute.---SWIM-SERV-021 Service operationsGuidance: provide a technical description of a service operation(M)

122OperationnameThe name of the operation. [SWIM-SERV-021]stringSWIM-SERV-021 Service operations

Guidance: Provide the name of the operation.

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.

Mandatory, minLength=1

123OperationdescriptionThe description of the operation.stringSWIM-SERV-021 Service operationsGuidance: Provide a description of the intent and the results of the service operation; andMandatory, minLength=5

124OperationidempotencyA value that indicates whether the operation is "idempotent" or "non-idempotent". [SWIM-SERV-021]CodeIdempotencyTypeSWIM-SERV-021 Service operationsGuidance: Optionally, select the appropriate code value.Optional

125OperationsynchronicityA value that indicates whether the operation is "synchronous" or "asynchronous". [SWIM-SERV-021]CodeSynchronicityTypeSWIM-SERV-021 Service operationsGuidance: Optionally, select the appropriate code value.Optional

126OperationtiProtocolMethodA protocol method used to implement the operation.stringSWIM-SERV-021 Service operations

Guidance: Optionally, provide the protocol method being used, such as the HTTP method.

Example: HTTP GET, HTTP POST.

Optional, minItems=0

127OperationpreconditionA description of the state or condition that should be true before the operation can proceed.stringSWIM-SERV-021 Service operationsGuidance: Describe the pre-condition(s) to execute the operation.Optional

128OperationprocessingConsiderationA step, constraint or action that is required to be taken on data received as part of a service request (input) in order to produce the desired output or change of internal state.ProcessingConsiderationSWIM-SERV-021 Service operations

Guidance: Provide the list of processing considerations relevant for service consumers.

This may be expressed as business rule.

Optional, minItems=0

129OperationoperationMessageA message associated with the operation. [SWIM-SERV-021]MessageSWIM-SERV-021 Service operations

Guidance: Describe the information exchanged by the service operation, as one or more input, output or error messages.

Mandatory, minItems=1

130Message---A discrete unit of communication intended by the source for consumption by a given recipient or group of recipients.---SWIM-SERV-021 Service operationsA type of message exchanged by the service operation(M)(O)(O)
131MessagedirectionA value that indicates whether the message is "input" or "output". [SWIM-SERV-021]CodeDirectionTypeSWIM-SERV-021 Service operations

Guidance: Select the code value corresponding to the direction of the message:

  • IN = input to the operation
  • OUT = output of the operation
MandatoryMandatoryMandatory
132MessagenameThe name of the message. [SWIM-SERV-021]stringSWIM-SERV-021 Service operations

Guidance: Provide the name of the message.

Note: this name will make the link to the information definition.

MandatoryMandatoryMandatory
133MessagedescriptionThe description of the message.stringSWIM-SERV-021 Service operations

Guidance: Optionally provide a description of the message.

Note: The message description is optional in the service description, but is mandatory in the information definition.

OptionalOptionalOptional
134MessageisFaultAn indication whether the message is a fault or not. [SWIM-SERV-021]booleanSWIM-SERV-021 Service operationsGuidance: Optionally indicate whether the message is an error message.OptionalOptionalOptional
135MessageheadersThe description of the headers.stringSWIM-SERV-021 Service operationsGuidance: Consider providing indication of those headers that are important for processing the message (E.g. Content Type XML, JSON, Content Enconding GZIP,..)OptionalOptionalOptional
136MessagebodyThe description of the body.stringSWIM-SERV-021 Service operationsGuidance: Consider indicating the detailed structure of the payload. E.g. AIXM_v.5.1.1.AIXM.AIXM Features.AirportHeliport.Airport/HeliportOptionalOptionalOptional
137ProcessingConsideration---A step or action that is required to be taken on data received as part of a service request (input) in order to produce the desired output or change of internal state.---SWIM-SERV-021 Service operationsGuidance: Consider indicating all constraints that further qualify a service operation (e.g. It does not accept request for a date in the past, or an update that is too close to the current value, or a certain frequency of request).(O)(O)(O)
138ProcessingConsiderationnameThe name of the processing consideration.stringSWIM-SERV-021 Service operationsGuidance. Provide a self descriptive name.MandatoryMandatoryMandatory
139ProcessingConsiderationdescriptionThe description of the processing consideration.stringSWIM-SERV-021 Service operationsGuidance. Explain the constraint in sufficient detail (e.g. It does not accept request for a date in the past, or an update that is too close to the current value, or a certain frequency of request).Mandatory

140ServiceBehaviour---The manner in which a service operates under normal and unexpected conditions. [SWIM-SERV-025]---SWIM-SERV-025 Service behaviour

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 behaviour description may refer to a SERVICE_BEHAVIOUR_DESCRIPTION document.

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.

(M)

141ServiceBehaviournameThe name of the service behaviour. [SWIM-SERV-025]stringSWIM-SERV-025 Service behaviourGuidance: provide a short name for the behaviourMandatory, minLength=1

142ServiceBehaviourdescriptionThe description of the service behaviour. [SWIM-SERV-025]stringSWIM-SERV-025 Service behaviour

Guidance:

Describe the behaviour as

  • the sequence of service operations; and
  • the handling of unexpected behaviour.

And / or make reference to a SERVICE_BEHAVIOUR_DESCRIPTION document.

Mandatory, minLength=5

143ServiceDescriptionReferences---References to complementary documents that provide additional details about the service.---multiple
(M)

144ServiceDescriptionReferencesimplementedStandardA standard used for the implementation of the service.ImplementedStandard

SWIM-SERV-010 Service standard reference


Guidance: use this list for

  • indicating whether the service adheres to a service standard (mandatory)
  • self declaration of conformance to the SWIM specifications (optional).
Mandatory, minItems=1

145ServiceDescriptionReferencesserviceDocumentA document that relates to the information service.Documentmultiple

Guidance: list here one or more documents related to the service description. At the minimum, the Information Definition must be provided.

Mandatory, minItems=1

146ImplementedStandard---A standard used for the implementation of the service.---

SWIM-SERV-010 Service standard reference


Guidance is split between "Serv_Std" and "SWIM_spec".

Rationale Serv_std: The reference to standards is essential information, fostering reuse.

Rule Serv_std: Mandatory

Rationale SWIM_spec: help understand the gap to SWIM spec conformance for CAND.

Rule SWIM_spec: Optional.

(M)

147ImplementedStandardstandardTypeThe type of implemented standard.CodeServiceStandardTypeSWIM-SERV-010 Service standard reference

Guidance Serv_Std: Select code SERVICE_STANDARD.

Guidance SWIM_spec: Select code of the concerned SWIM spec.

Mandatory

148ImplementedStandardisConformantAn indication whether the information service conforms to a reference. [SWIM-SERV-010]booleanSWIM-SERV-010 Service standard reference

Guidance Serv_Std: Indicate whether the service adheres to a service standard.

Guidance SWIM_spec: Indicate whether the service conforms to the spec.

Mandatory

149ImplementedStandardtitleThe name by which the document is formally known. [SWIM-SERV-005;SWIM-SERV-010]stringSWIM-SERV-010 Service standard reference

Rule Serv_Std: Mandatory when adherence. No use otherwise.

Guidance Serv_Std: provide the name of the service standard or the title of the service standard document.

Rule SWIM_spec: Optional (no added value)

Mandatory Conditional

(Optional in Schema)



150ImplementedStandardversionThe current version or revision level of the document.stringSWIM-SERV-010 Service standard reference

Rule Serv_Std: Mandatory when adherence. No use otherwise.

Guidance Serv_Std: makes clear the version of the adhered service standard.

Guidance SWIM_spec: provide version of spec (eg "1.0").

Mandatory Conditional

(Optional in Schema)



151ImplementedStandardconformanceStatementA statement about the degree of conformance of the service against the standard.stringSWIM-SERV-010 Service standard reference

Rule Serv_Std: Optional when adherence. No use otherwise.

Guidance Serv_Std: indicate implemented options and/or deviations, if any.

Guidance SWIM_spec: Can be used to indicate the gap to conformance.

Mandatory Conditional

(Optional in Schema)



152ImplementedStandarddescriptionThe description of the entity.stringSWIM-SERV-010 Service standard reference

Rule Serv_Std: Optional when adherence. No use otherwise.

Guidance Serv_Std: optionally provide a description of the service standard.

Guidance SWIM_spec: leave empty.

Optional

153ImplementedStandardreferenceAn external reference at which the standard can be retrieved or consulted.stringSWIM-SERV-010 Service standard reference

Rule Serv_Std: Optional when adherence. No use otherwise.

Guidance Serv_Std: optionally provide an external link to the service standard.

Note: In case of doubt, the version field makes clear the version of the standard.

Guidance SWIM_spec: provide a reference to the conformance assessment report.

Optional

154Document---A piece of written, printed, or electronic matter that provides information or evidence or that serves as an official record.---

SWIM-SERV-020 Machine-readable interface 

SWIM-SERV-026 Model view

SWIM-SERV-029 Examples of code  

Rationale: The JSON service description does not include all information useful to service consumers. Some information is made available separately (eg Information Definition), some other are best as separate files (eg machine readable service description).

Guidance: Provide at least a document with type INFORMATION_DEFINITION

See as well Guidance on serviceDocument.

(M)

155DocumentdocumentTypeThe type of document.CodeDocumentTypemultipleGuidance: Select the code according to usage described in Code Lists walk-through.Mandatory

156DocumenttitleThe name by which the document is formally known. [SWIM-SERV-005;SWIM-SERV-010]stringmultiple
Mandatory, minLength=5

157DocumentversionThe current version or revision level of the document.stringmultipleGuidance: in absence of a version, consider providing a reference date.Mandatory, minLength=1

158DocumentdescriptionThe description of the document.string

multiple

SWIM-SERV-026 Model view

Guidance for SERVICE_MODEL: declare the notation used to express the model viewOptional

159DocumentreferenceAn external reference at which the document can be retrieved or consulted.stringmultipleGuidance: in absence of an external reference, leave empty. Later on, Registry may help providing a reference.Optional