The registry uses an information schema to structure service information.
In this page it is provided the schema (at the bottom of this page) as well as guidelines on how to understand the different elements part of this schema .
Element Name | Attribute Name | Description | Attribute Type | Service Spec Trace | Guideline | COMP Rule | CAND Rule | DEFN Rule |
InformationService | --- | A type of service that provides an ATM information sharing capability. | --- | SWIM-SERV-001 Description coverage | Guidance: Describe here your prospective service, operational service or service definition. | Mandatory | same | same |
InformationService | descriptionInformation | A container for Service Description metadata. | DescriptionInformation | multiple | Note: This information is about the document more than the underlying service. | Mandatory | same | same |
InformationService | name | A piece of identifying information that gives stakeholders a way to reference or identify a service. [SWIM-SERV-006] | string | SWIM-SERV-006 Service identification | The 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=1 | same | same |
InformationService | version | The version of the information service. [SWIM-SERV-006] | string | SWIM-SERV-006 Service identification | Structured 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=1 | same | same |
InformationService | serviceAbstract | A brief summary of the service offering. [SWIM-SERV-007] | string | SWIM-SERV-007 Service abstract | Rationale: This information supports the decisions on whether the described service is suitable for use in a particular situation. | Mandatory, minLength=5 | same | same |
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". | ||||||||
InformationService | serviceProvision | A container for information about who provides the service, when and how it is supported. | ServiceProvision | SWIM-SERV-008 Service provider | Rationale: Knowing the service provider is essential to business experts. | Mandatory | same | Optional if providerType moved outside |
Rationale: Point of contact allows getting additional information regarding the service. | ||||||||
InformationService | serviceCategorisation | A 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 | Rationale: Service category information allows discovering services by a series of classification criteria. | Mandatory | same | same |
SWIM-REG-0004 Service categorization | ||||||||
InformationService | serviceGeneralDescription | A container for information about what the service provides, its purpose and under which conditions and quality levels it is provided. | ServiceGeneralDescription | multiple | Mandatory | same | same | |
InformationService | serviceInformationDescription | A container for the description of the information exchanged by the information service. | ServiceInformationDescription | multiple | Rationale: Provide a description of the information/data that is exchanged by the service. | Mandatory | Mandatory | Mandatory |
InformationService | serviceTechnicalDescription | A container for information about the security mechanisms, technical constraints and monitoring of the information service. | ServiceTechnicalDescription | multiple | Note: the attribute is mandatory, so that authors consider the underlying Mandatory Conditional information. | Mandatory | ||
InformationService | serviceInterface | The means by which the underlying capabilities of a service are accessed. | Interface | multiple | Guidance: Describe one or more interfaces. | Mandatory, minItems=1 | ||
Provide all interfaces: provider side and consumer side interfaces. | ||||||||
InformationService | serviceDescriptionReferences | A container for references to documents describing specific aspects of the service instance. | ServiceDescriptionReferences | multiple | Mandatory | |||
DescriptionInformation | --- | Information identifying the service description. | --- | multiple | Note: This groups information specific to the service description, and not about the underlying service. | Mandatory | same | same |
DescriptionInformation | serviceDescriptionIdentification | Information identifying the service description. | ServiceDescription | SWIM-SERV-005 Description identification | Mandatory | same | same | |
DescriptionInformation | abbreviations | Abbreviations or acronyms used by the service description. | Abbreviation | SWIM-SERV-003 Define abbreviations | Guidance: Define all abbreviations and acronyms used in the description. Unless they are systematically made explicit, such as in "IFR (Instrument Flight Rules)". | Mandatory, minItems=0 | same | same |
ServiceDescription | --- | Information needed in order to use, or consider using, a service. | --- | SWIM-SERV-005 Description identification | Rationale: supports the identification and citation of a service description. | Mandatory | same | same |
ServiceDescription | serviceDescriptionTitle | The name by which the document is formally known. [SWIM-SERV-005;SWIM-SERV-010] | string | SWIM-SERV-005 Description identification | Mandatory, minLength=5 | same | same | |
ServiceDescription | serviceDescriptionEdition | Manifestations of a publication embodying essentially the same content. [SWIM-SERV-005] | string | SWIM-SERV-005 Description identification | 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. | Mandatory, minLength=1 | same | same |
ServiceDescription | serviceDescription ReferenceDate | The date at which the document has been published. [SWIM-SERV-005] | string | SWIM-SERV-005 Description identification | Mandatory, format is "yyyy-mm-dd" | same | same | |
Abbreviation | --- | 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. | Mandatory | same | same |
Abbreviation | name | The name of the abbreviation. [SWIM-SERV-003] | string | SWIM-SERV-003 Define abbreviations | The abbreviated form eg "IFR". | Mandatory, minLength=1 | same | same |
Verification: Check if the abbreviation exists in AIRM, verify the term is the same. | ||||||||
Abbreviation | description | The description of the abbreviation. | string | SWIM-SERV-003 Define abbreviations | The 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=5 | same | same |
ServiceProvision | --- | Description of who provides the service, when and how it is supported. | --- | SWIM-SERV-008 Service provider | Mandatory | |||
ServiceProvision | provider | The full official name of the organisation. [SWIM-SERV-008] | string | SWIM-SERV-008 Service provider | Rationale: Knowing the service provider is essential to business experts. | Mandatory, minLength=1 | ||
ServiceProvision | providerDescription | Description of the organisational unit responsible for the service. [SWIM-SERV-008] | string | SWIM-SERV-008 Service provider | Guidance: Provide a small description of the organisation and/or the unit responsible for the service | Mandatory, minLength=5 | ||
Consider including information on provider certification when relevant for the service being described (e.g. for a Meteorological service). | ||||||||
ServiceProvision | providerType | The type of service provider. | CodeStakeholderType | SWIM-SERV-009 Service categories | Mandatory, minItems=1 | |||
ServiceProvision | dateInOperation | Date at which the service went into operation or is planned to become operational. | string | SvcOvw | Provide the date at which this service version became operational. | Mandatory, format is "yyyy-mm-dd" | ||
Note: The date at which the service became operational for the first time may be mentioned in the service abstract. | ||||||||
ServiceProvision | serviceSupport | Provision of material and guidance necessary for the use of the information service. | string | SvcOvw | Specify days and hours the information service provider can be contacted by users requiring support for the provided service. | Optional | same | |
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. | ||||||||
ServiceProvision | pointOfContact | A person or group within the service provider organization, suitable for making a human contact for any purpose. [SWIM-SERV-008] | PointOfContact | SWIM-SERV-008 Service provider | Provide one or more points of contact where additional information can be obtained, including name, contact information and role. | Mandatory, minItems=1 | ||
PointOfContact | --- | A person or group within an organization, suitable for making a human contact for any purpose. [SWIM-SERV-008] | --- | SWIM-SERV-008 Service provider | Guidance: At least one contact information is required. Example contact information: email address; postal address; phone number; URL. | Mandatory | ||
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”. | ||||||||
PointOfContact | name | The name of the point of contact. | string | SWIM-SERV-008 Service provider | Mandatory, minLength=1 | |||
PointOfContact | description | The description of the point of contact. | string | SWIM-SERV-008 Service provider | Describe the role / function of the point of contact. When applicable add contact info such as URL link or postal address. | Mandatory, minLength=5 | ||
PointOfContact | An electronic mail address used to correspond in writing with the point of contact. | string | SWIM-SERV-008 Service provider | Guidance: At least one contact information is required. | Optional | |||
PointOfContact | phoneNumber | A telephone number used to communicate orally with the point of contact. | string | SWIM-SERV-008 Service provider | Guidance: At least one contact information is required. | Optional | ||
ServiceCategorisation | --- | 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 categories | Rationale: Service category information allows discovering services by a series of classification criteria. | Mandatory | same | same |
ServiceCategorisation | serviceType | An 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_CANDIDATE | same, value= DEFINITION |
ServiceCategorisation | lifeCycleStage | A 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) | |
ServiceCategorisation | businessActivityType | The type of business activity. | CodeBusinessActivityType | SWIM-REG-0004 Service categorization | Select one or more code values | Mandatory, minItems=1 | ||
ServiceCategorisation | intendedConsumer | The types of service consumers that this service is intended to serve. | CodeStakeholderType | SWIM-REG-0004 Service categorization | Select one or more code values | Mandatory, minItems=1 | ||
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. | ||||||||
ServiceCategorisation | informationCategory | TBD | CodeInformationExchangeCategory | SWIM-SERV-009 Service categories | Select one or more code values | Mandatory, minItems=1 | ||
ServiceCategorisation | application MessageExchangePattern | The type of Application MEP. [SWIM-SERV-017] | CodeApplication MessageExchangePatternType | SWIM-SERV-017 Message exchange pattern | Select one or more code values. | Mandatory, minItems=1 | ||
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). | ||||||||
ServiceCategorisation | geospatialCategorisation | The 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. | Optional | ||
Guidance: Consider summarising it in the service abstract as well. | ||||||||
GeographicalExtent | --- | The geographic coverage of the information provided by the service. | --- | SWIM-REG-0004 Service categorization | Guidance: Geographical coverage may be expressed in terms of ICAO state, FIR, Aerodrome. | Optional | same | same |
SERV-OVW-008 Geographical extent | Rationale: Allow consumer to understand the geographical coverage of the service. | |||||||
GeographicalExtent | stateICAONationalityLetters | Nationality letters of a State as defined by ICAO. [SWIM-SERV-009] | string | SWIM-REG-0004 Service categorization | List zero or more code values. Applicable values are in ICAO doc 7910. | Optional | same | same |
GeographicalExtent | firICAOLocationIndicator | A 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 values are in ICAO doc 7030. | Optional | same | same |
GeographicalExtent | aerodrome ICAOLocationIndicator | A 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 values are in ICAO doc 7910. | Optional | same | same |
ServiceGeneralDescription | --- | Description of the service in terms of what it provides, the purpose and under which conditions and quality levels the service is provided. | --- | multiple | Mandatory | same | same | |
ServiceGeneralDescription | operationalNeed | The operational need fulfilled by the service [SWIM-SERV-011] | OperationalNeed | SWIM-SERV-011 Operational needs | List the operational needs such as operational context and requirements that are at the origin of the service. | Mandatory, minItems=1 | same | same |
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. | ||||||||
ServiceGeneralDescription | functionality | A type of activity describing the functionality of a service. [SWIM-SERV-012] | Functionality | SWIM-SERV-012 Service functionality | Express the functionality offered by the service as a list of service functions. | Mandatory, minItems=1 | same | same |
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. | ||||||||
ServiceGeneralDescription | accessAndUseCondition | A condition which applies to accessing and using the service, such as legal constraint, service policies, service consumption constraints and security constraints. [SWIM-SERV-013] | AccessAndUseCondition | SWIM-SERV-013 Access and use conditions | List the conditions that apply to access or use the service. | Mandatory, minItems=1 | ||
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. | ||||||||
ServiceGeneralDescription | qualityOfService | The degree or level of confidence that the performance of a service meets users requirements. [SWIM-SERV-014] | QualityOfService | SWIM-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. | Mandatory, minItems=3 | ||
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. | ||||||||
ServiceGeneralDescription | concepts | 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. | Concept | SWIM-SERV-ADD Additional info | List additional information deemed useful for a good use of the service. | Optional, minItems=0 | same | same |
SWIM-SERV-024 Filter capabilities | Use as well for pre-defined uses such as, for instance, Filter capabilities or Sources of information. | |||||||
SERV-OVW-008 Geographical extent | 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). | |||||||
SERV-OVW-017 Sources of information | ||||||||
ServiceGeneralDescription | validation | Activity whereby a service is checked for conformance with the service objectives and requirements. [SWIM-SERV-027] | ValidationOfService | SWIM-SERV-027 Service validation | List one or more validation activities. | Mandatory, minItems=1 | Optional | |
OperationalNeed | --- | 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. | Mandatory | same | same |
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. | ||||||||
OperationalNeed | name | The name of the operational requirement. | string | SWIM-SERV-011 Operational needs | Guidance: provide a short name for the operational need | Mandatory, minLength=1 | same | same |
OperationalNeed | description | Description of the operational needs fulfilled by the service. Includes or refers to information exchange requirements [SWIM-SERV-011]. | string | SWIM-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. | Mandatory, minLength=5 | same | same |
Make explicit the needs addressed by the service. | ||||||||
List the requirements at the origin of the service (eg IERs). | ||||||||
Functionality | --- | A type of activity describing the functionality of a service. | --- | SWIM-SERV-012 Service functionality | Mandatory | same | same | |
Functionality | name | The name of the service function. | string | SWIM-SERV-012 Service functionality | Provide a short name for the service function | Mandatory, minLength=1 | same | same |
Functionality | description | Description of the service function. [SWIM-SERV-012] | string | SWIM-SERV-012 Service functionality | Describe here the service function. | Mandatory, minLength=5 | same | same |
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. | ||||||||
Functionality | realWorldEffect | 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. [SWIM-SERV-012] | string | SWIM-SERV-012 Service functionality | Describe here the real-world-effect, if any. | Mandatory, minLength=0 | same | same |
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. | ||||||||
AccessAndUseCondition | --- | 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 | Mandatory | |||
AccessAndUseCondition | type | The type of service access or use condition. [SWIM-SERV-013] | CodeAccessAndUseConditionType | SWIM-SERV-013 Access and use conditions | Select the code value indicating the type of condition: LEGAL CONSTRAINT , SERVICE POLICY, SERVICE CONSUMPTION CONSTRAINT, SECURITY CONSTRAINT, OTHER. | Mandatory | ||
AccessAndUseCondition | name | The name of the condition. | string | SWIM-SERV-013 Access and use conditions | Provide a short name for the condition. | Mandatory, minLength=1 | ||
AccessAndUseCondition | description | Description 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. | string | SWIM-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. | Mandatory, minLength=5 | ||
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) | ||||||||
QualityOfService | --- | The degree or level of confidence that the performance of a service meets users requirements. | --- | SWIM-SERV-014 Quality of service | Mandatory | |||
QualityOfService | name | The name of the quality of service. [SWIM-SERV-014] | string | SWIM-SERV-014 Quality of service | Provide a clear and concise name for the quality of service, such as "Availability", "Response time", "Throughput". | Mandatory, minLength=1 | ||
Consider as well describing less quantitative aspects such as "Integrity", "Confidentiality" and other service related qualities defined in ISO 25010 | ||||||||
QualityOfService | description | Description 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 25010 | string | SWIM-SERV-014 Quality of service | See Notes / Examples of the requirement. | Mandatory, minLength=5 | ||
Concept | --- | 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 | Include useful information that could not fit nicely in another section. | Optional | same | same |
SWIM-SERV-024 Filter capabilities | Use as well to cope with shortcomings of the schema. Eg Filter capabilities. | |||||||
SERV-OVW-008 Geographical extent | 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. | |||||||
SERV-OVW-017 Sources of information | ||||||||
Concept | name | The name of the concept. | string | SWIM-SERV-ADD Additional info | Guidance: Define a name that makes clear what the description is about. | Mandatory, minLength=1 | ||
For -predefine use, use the name as defined below precisely (which would allow automatic processing): | ||||||||
SWIM-SERV-024 Filter capabilities "Filter capabilities" | ||||||||
SERV-OVW-008 Geographical extent "Geographical extent" | ||||||||
SERV-OVW-017 Sources of information "Sources of information" | ||||||||
Concept | description | Description of the concept. | string | SWIM-SERV-ADD Additional info | Provide the description. | Mandatory, minLength=5 | ||
ValidationOfService | --- | 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. | Mandatory | ||
Rationale: User needs to know how the information service was validated in order to have confidence in the service. | ||||||||
ValidationOfService | type | The type of service validation. [SWIM-SERV-027] | CodeServiceValidationType | SvcOvw | Select the code value corresponding to the validation method used, (User Validated, Self-Validation, Collaborative, or Independent) | Optional | ||
SWIM-SERV-027 Service validation | Note: Is mandatory except for the case not validated. | |||||||
ValidationOfService | description | The description of the service validation. [SWIM-SERV-027] | string | SWIM-SERV-027 Service validation | Include a brief statement on the validation results, and if/how the potential consumers may obtain the validation evidence. | Mandatory | ||
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. | ||||||||
ServiceInformationDescription | --- | 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. | Mandatory | Mandatory | Mandatory |
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. | ||||||||
ServiceInformationDescription | informationDefinition | A formal representation of information concepts or data concepts. [SWIM-SERV-022] | InformationDefinition | SWIM-SERV-022 Information definition | Rationale: Enables to understand the information provided by the service, with a specific focus to the semantics of the information | Mandatory, minItems=1 | Mandatory | Mandatory |
ServiceInformationDescription | exchangeSchema | Formal description of the data involved in an information exchange. | ExchangeSchema | SWIM-SERV-019 Protocols and data format | List the data formats used. | Mandatory, minItems=1 | Optional | Optional |
InformationDefinition | --- | A formal representation of information concepts or data concepts. [SWIM-SERV-022] | --- | SWIM-SERV-022 Information definition | Rationale: Enables to understand the information provided by the service, with a specific focus to the semantics of the information | Mandatory | Mandatory | Mandatory |
InformationDefinition | name | The name of the Information Definition. [SWIM-SERV-022] | string | SWIM-SERV-022 Information definition | Guidance: 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 Definition | Mandatory, minLength=1 | Mandatory | Mandatory |
InformationDefinition | description | The description of the Information Definition. [SWIM-SERV-022] | string | SWIM-SERV-022 Information definition | Guidance: introduce this information definition. Eg use the information definition abstract SWIM-INFO-005 Information definition scope. | Mandatory, minLength=5 | Optional | Optional |
Guidance: Make sure to have one or several service documents with type INFORMATION_DEFINITION. See Guidance on serviceDocument. | ||||||||
InformationDefinition | airmConformant | An indication whether the information definition used by the service conforms to the ATM Information Reference Model. [SWIM-SERV-023] | boolean | SWIM-SERV-023 AIRM conformance | Guidance: Indicate whether the service payload has semantic correspondence with the AIRM. | Mandatory | Mandatory | Mandatory |
InformationDefinition | airmVersion | The applicable version of the ATM Information Reference Model. [SWIM-SERV-023] | string | SWIM-SERV-023 AIRM conformance | Rule: Mandatory when airmConformant is true. No use otherwise. | Conditional Mandatory | Optional | same |
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. | ||||||||
ExchangeSchema | --- | Formal description of the data involved in an information exchange. | --- | SWIM-SERV-019 Protocols and data format | Rationale: Enables to understand data format(s). | Mandatory | Mandatory | Optional |
ExchangeSchema | name | The name of the exchange schema. [SWIM-SERV-019] | string | SWIM-SERV-019 Protocols and data format | Guidance: Provide the name of the data format that is used to exchange data via the service interface. | Mandatory | Mandatory | Mandatory |
ExchangeSchema | schemaLanguage | Description of the language used (e.g. XML, JSON). [SWIM-SERV-019] | string | SWIM-SERV-019 Protocols and data format | Guidance: Indicate the language in which the data format is expressed (e.g. XSD, JSON, natural language,..) | Mandatory | Optional | Optional |
ExchangeSchema | reference | A reference to the exchange schema containing the specifications of the data structures. | string | SWIM-SERV-019 Protocols and data format | Guidance: Indicate with a reference the location of where the data format is defined (e.g. See service documents) | Optional | Optional | Optional |
ServiceTechnicalDescription | --- | Description of the technical aspects of the service including data structures, interface and operations behaviour, security mechanisms and technical constraints | --- | multiple | Note: It may be possible that this results in an empty object. | Mandatory | ||
ServiceTechnicalDescription | technicalConstraint | A characteristic of the environment or larger system within which the service operates. [SWIM-SERV-015] | TechnicalConstraint | SWIM-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. | Optional, minItems=0 | same | same |
Guidance: When technical constraints exist, it is mandatory to describe them. | ||||||||
Guidance: Describe zero or more technical constraints. | ||||||||
ServiceTechnicalDescription | securityMechanism | A process (or a device incorporating such a process) that is utilized or implemented by the service in order to address a security threat. | SecurityMechanism | SWIM-SERV-019 Protocols and data format | Guidance: list the (security protocols) that are global for the service, if any. | Optional, minItems=0 | ||
Note: In Interface.interfaceBindingDescription list per interface the protocols not already mentioned here. | ||||||||
ServiceTechnicalDescription | serviceMonitoring | A service monitoring mechanism available to service consumers. [SWIM-SERV-028] | ServiceMonitoring | SWIM-SERV-028 Service monitoring | Guidance: When such a mechanism is made available to consumers, it is mandatory to describe it. | Conditional Mandatory | Optional | Optional |
Rationale: Allow the service consumer to use the available mechanism and monitor the service. | ||||||||
SecurityMechanism | --- | 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. | Mandatory | ||
See as well Interface.interfaceBindingDescription | ||||||||
SecurityMechanism | name | The name of the security mechanism. | string | SWIM-SERV-019 Protocols and data format | Provide the name and version of the protocol. | Mandatory | ||
Eg X.509v3 Client Certificate | ||||||||
SecurityMechanism | description | The description of the security mechanism. | string | SWIM-SERV-019 Protocols and data format | Describe the mechanism | Mandatory | ||
Eg Authentication performed based on X.509 client certificates over a secured connection based on TLS. | ||||||||
SecurityMechanism | type | The type of security mechanism. | CodeSecurityMechanismType | SWIM-SERV-019 Protocols and data format | Select zero or more code values that indicate the type of security mechanism. | Optional, minItems=0 | ||
TechnicalConstraint | --- | 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. | Optional | same | same |
Example technical constraints: firewall, minimum bandwidth or server resources, interface language, integration pattern, protocol and communication ports. | ||||||||
TechnicalConstraint | name | The name of the technical constraint. [SWIM-SERV-015] | string | SWIM-SERV-015 Technical constraint | Guidance: Provide a concise name for the technical constraint. | Mandatory, minLength=1 | ||
TechnicalConstraint | description | The description of the technical constraint. [SWIM-SERV-015] | string | SWIM-SERV-015 Technical constraint | Guidance: describe the technical constraint. | Mandatory, minLength=5 | ||
ServiceMonitoring | --- | Tracking state and operational conditions related to the execution, performance, and real-world effects of services. | --- | SWIM-SERV-028 Service monitoring | Note: Mandatory when available. | Optional | same | same |
ServiceMonitoring | monitoringDescription | Description if available of the existing monitoring capabilities and how this can be used by the consumer. [SWIM-SERV-028]. | string | SWIM-SERV-028 Service monitoring | Guidance: provide the description so that the mechanism can be used by the consumer. | Mandatory, minLength=5 | ||
Interface | --- | 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. | Mandatory | ||
Interface | name | The name of the interface. [SWIM-SERV-016] | string | SWIM-SERV-016 Service interfaces | Mandatory, minLength=1 | |||
Interface | description | The description of the entity. [SWIM-SERV-016] | string | SWIM-SERV-016 Service interfaces | Guidance: a textual description of the service interface including its purpose. | Mandatory, minLength=5 | ||
Interface | interfaceProvisionSide | An indication that the interface is a provider side interface or a consumer side interface. [SWIM-SERV-016] | CodeInterfaceSideType | SWIM-SERV-016 Service interfaces | Guidance: select the appropriate value. | Mandatory | ||
Interface | tiPrimitive MessageExchangePattern | The type of primitive MEP implemented by the interface. | CodePrimitive MessageExchangePatternType | N/A | Rationale: makes explicit the MEP used by the operations within this interface. | Mandatory | ||
Guidance: select the appropriate value. | ||||||||
Interface | serviceInterfaceBinding | An interface binding that enables services to exchange data with consuming applications. [SWIM-SERV-018] | CodeServiceInterfaceBindingType | SWIM-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. | Mandatory | ||
Guidance: select the appropriate code value. | ||||||||
Note: the code value also indicates the TI profile and version. | ||||||||
Interface | networkInterfaceBinding | An interface binding that enables the SWIM TI to exchange data with the network. [SWIM-SERV-018] | CodeNetworkInterfaceBindingType | SWIM-SERV-018 TI Profile and bindings | Guidance: select the appropriate code value. | Mandatory | ||
Interface | interfaceBindingDescription | Complementary 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 | Rationale: Makes explicit within the service description what the protocols are. | Mandatory, minLength=1 | ||
SWIM-SERV-019 Protocols and data format | 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. | ||||||||
Interface | endPoint | Location at which information is received to invoke and configure interaction. [SWIM-SERV-016] | EndPoint | SWIM-SERV-016 Service interfaces | Rationale: This information facilitates the the understanding of the location to access the interface. | Mandatory, minItems=1 | ||
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. | ||||||||
Interface | operation | Specification of a transformation or query that an object may be called to execute. [SWIM-SERV-021] | Operation | SWIM-SERV-021 Service operations | Rationale: The consumer needs to know which service operations are available to be called for the expected result. | Mandatory, minItems=1 | ||
Guidance: describe all service operations of the interface (one or more operations). | ||||||||
Interface | behaviour | The manner in which a service operates under normal and unexpected conditions. [SWIM-SERV-025] | ServiceBehaviour | SWIM-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. | Mandatory, minItems=1 | ||
Guidance: provide one or more behaviours. | ||||||||
Note: The behaviour description may refer to a SERVICE_BEHAVIOUR_DESCRIPTION document. | ||||||||
Note: 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. | ||||||||
EndPoint | --- | Location at which information is received to invoke and configure interaction. | --- | SWIM-SERV-016 Service interfaces | Rationale: This information facilitates the the understanding of the location to access the interface. | Mandatory | Optional | NA |
EndPoint | name | The name of the end point. | string | SWIM-SERV-016 Service interfaces | Guidance: Provide a concise name that makes clear the usage of the end-point. Example: "Operational", "Pre-operational evaluation". | Mandatory | Mandatory | NA |
EndPoint | description | The description of the entity. | string | SWIM-SERV-016 Service interfaces | Guidance: If useful, provide additional information on the end-point, such as usage, accessibility, etc. | Optional | Optional | NA |
EndPoint | address | A network-visible identifier used to designate specific endpoints in a network. [SWIM-SERV-016] | string | SWIM-SERV-016 Service interfaces | Guidance: provide the fully qualified network address at which the interface can be accessed | Mandatory | Optional | NA |
EndPoint | addressableResource | A resource that can be addressed through this End Point. | 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. | Optional | Optional | NA |
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) | ||||||||
Resource | --- | 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. | Optional | Optional | NA |
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) | ||||||||
Resource | type | The type of resource. | CodeTechnicalResourceType | N/A | Rationale: Indicates the type of the resource: QUEUE, TOPIC,.. | Optional | Optional | NA |
Resource | name | The name of the resource. | string | N/A | Guidance: provide a self descriptive name | Mandatory, minLength=1 | Mandatory | NA |
Resource | description | The description of the resource. | string | N/A | Guidance: Consider providing additional information that enables to understand the resource ( E.g. For QUEUE the behavior FIFO) | Optional | Optional | NA |
Operation | --- | Specification of a transformation or query that an object may be called to execute. | --- | SWIM-SERV-021 Service operations | Guidance: provide a technical description of a service operation | Mandatory | ||
Operation | name | The name of the operation. [SWIM-SERV-021] | string | SWIM-SERV-021 Service operations | Guidance: Provide the name of the operation. | Mandatory, minLength=1 | ||
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. | ||||||||
Operation | description | The description of the operation. | string | SWIM-SERV-021 Service operations | Guidance: Provide a description of the intent and the results of the service operation; and | Mandatory, minLength=5 | ||
Operation | idempotency | A value that indicates whether the operation is "idempotent" or "non-idempotent". [SWIM-SERV-021] | CodeIdempotencyType | SWIM-SERV-021 Service operations | Guidance: Optionally, select the appropriate code value. | Optional | ||
Operation | synchronicity | A value that indicates whether the operation is "synchronous" or "asynchronous". [SWIM-SERV-021] | CodeSynchronicityType | SWIM-SERV-021 Service operations | Guidance: Optionally, select the appropriate code value. | Optional | ||
Operation | tiProtocolMethod | A protocol method used to implement the operation. | string | SWIM-SERV-021 Service operations | Guidance: Optionally, provide the protocol method being used, such as the HTTP method. | Optional, minItems=0 | ||
Example: HTTP GET, HTTP POST. | ||||||||
Operation | precondition | A description of the state or condition that should be true before the operation can proceed. | string | SWIM-SERV-021 Service operations | Guidance: Describe the pre-condition(s) to execute the operation. | Optional | ||
Operation | processingConsideration | A 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. | ProcessingConsideration | SWIM-SERV-021 Service operations | Guidance: Provide the list of processing considerations relevant for service consumers. | Optional, minItems=0 | ||
This may be expressed as business rule. | ||||||||
Operation | operationMessage | A message associated with the operation. [SWIM-SERV-021] | Message | SWIM-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 | ||
Message | --- | A discrete unit of communication intended by the source for consumption by a given recipient or group of recipients. | --- | SWIM-SERV-021 Service operations | A type of message exchanged by the service operation | Mandatory | Optional | Optional |
Message | direction | A value that indicates whether the message is "input" or "output". [SWIM-SERV-021] | CodeDirectionType | SWIM-SERV-021 Service operations | Guidance: Select the code value corresponding to the direction of the message: | Mandatory | Mandatory | Mandatory |
IN = input to the operation | ||||||||
OUT = output of the operation | ||||||||
Message | name | The name of the message. [SWIM-SERV-021] | string | SWIM-SERV-021 Service operations | Guidance: Provide the name of the message. | Mandatory | Mandatory | Mandatory |
Note: this name will make the link to the information definition. | ||||||||
Message | description | The description of the message. | string | SWIM-SERV-021 Service operations | Guidance: Optionally provide a description of the message. | Optional | Optional | Optional |
Note: The message description is optional in the service description, but is mandatory in the information definition. | ||||||||
Message | isFault | An indication whether the message is a fault or not. [SWIM-SERV-021] | boolean | SWIM-SERV-021 Service operations | Guidance: Optionally indicate whether the message is an error message. | Optional | Optional | Optional |
Message | headers | The description of the headers. | string | SWIM-SERV-021 Service operations | Guidance: Consider providing indication of those headers that are important for processing the message (E.g. Content Type XML, JSON, Content Enconding GZIP,..) | Optional | Optional | Optional |
Message | body | The description of the body. | string | SWIM-SERV-021 Service operations | Guidance: Consider indicating the detailed structure of the payload. E.g. AIXM_v.5.1.1.AIXM.AIXM Features.AirportHeliport.Airport/Heliport | Optional | Optional | Optional |
ProcessingConsideration | --- | 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 operations | Guidance: 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). | Optional | Optional | Optional |
ProcessingConsideration | name | The name of the processing consideration. | string | SWIM-SERV-021 Service operations | Guidance. Provide a self descriptive name. | Mandatory | Mandatory | Mandatory |
ProcessingConsideration | description | The description of the processing consideration. | string | SWIM-SERV-021 Service operations | Guidance. 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 | ||
ServiceBehaviour | --- | The manner in which a service operates under normal and unexpected conditions. [SWIM-SERV-025] | --- | SWIM-SERV-025 Service behaviour | Examples of behaviour specification: | Mandatory | ||
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. | ||||||||
ServiceBehaviour | name | The name of the service behaviour. [SWIM-SERV-025] | string | SWIM-SERV-025 Service behaviour | Guidance: provide a short name for the behaviour | Mandatory, minLength=1 | ||
ServiceBehaviour | description | The description of the service behaviour. [SWIM-SERV-025] | string | SWIM-SERV-025 Service behaviour | Guidance: | Mandatory, minLength=5 | ||
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. | ||||||||
ServiceDescriptionReferences | --- | References to complementary documents that provide additional details about the service. | --- | multiple | Mandatory | |||
ServiceDescriptionReferences | implementedStandard | A standard used for the implementation of the service. | ImplementedStandard | SWIM-SERV-010 Service standard reference | Guidance: use this list for | Mandatory, minItems=1 | ||
indicating whether the service adheres to a service standard (mandatory) | ||||||||
self declaration of conformance to the SWIM specifications (optional). | ||||||||
ServiceDescriptionReferences | serviceDocument | A document that relates to the information service. | Document | multiple | Guidance: list here one or more documents related to the service description. At the minimum, the Information Definition must be provided. | Mandatory, minItems=1 | ||
ImplementedStandard | --- | A standard used for the implementation of the service. | --- | SWIM-SERV-010 Service standard reference | Guidance is split between "Serv_Std" and "SWIM_spec". | Mandatory | ||
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. | ||||||||
ImplementedStandard | standardType | The type of implemented standard. | CodeServiceStandardType | SWIM-SERV-010 Service standard reference | Guidance Serv_Std: Select code SERVICE_STANDARD. | Mandatory | ||
Guidance SWIM_spec: Select code of the concerned SWIM spec. | ||||||||
ImplementedStandard | isConformant | An indication whether the information service conforms to a reference. [SWIM-SERV-010] | boolean | SWIM-SERV-010 Service standard reference | Guidance Serv_Std: Indicate whether the service adheres to a service standard. | Mandatory | ||
Guidance SWIM_spec: Indicate whether the service conforms to the spec. | ||||||||
ImplementedStandard | title | The name by which the document is formally known. [SWIM-SERV-005;SWIM-SERV-010] | string | SWIM-SERV-010 Service standard reference | Rule Serv_Std: Mandatory when adherence. No use otherwise. | Mandatory Conditional | ||
Guidance Serv_Std: provide the name of the service standard or the title of the service standard document. | (Optional in Schema) | |||||||
Rule SWIM_spec: Optional (no added value) | ||||||||
ImplementedStandard | version | The current version or revision level of the document. | string | SWIM-SERV-010 Service standard reference | Rule Serv_Std: Mandatory when adherence. No use otherwise. | Mandatory Conditional | ||
Guidance Serv_Std: makes clear the version of the adhered service standard. | (Optional in Schema) | |||||||
Guidance SWIM_spec: provide version of spec (eg "1.0"). | ||||||||
ImplementedStandard | conformanceStatement | A statement about the degree of conformance of the service against the standard. | string | SWIM-SERV-010 Service standard reference | Rule Serv_Std: Optional when adherence. No use otherwise. | Mandatory Conditional | ||
Guidance Serv_Std: indicate implemented options and/or deviations, if any. | (Optional in Schema) | |||||||
Guidance SWIM_spec: Can be used to indicate the gap to conformance. | ||||||||
ImplementedStandard | description | The description of the entity. | string | SWIM-SERV-010 Service standard reference | Rule Serv_Std: Optional when adherence. No use otherwise. | Optional | ||
Guidance Serv_Std: optionally provide a description of the service standard. | ||||||||
Guidance SWIM_spec: leave empty. | ||||||||
ImplementedStandard | reference | An external reference at which the standard can be retrieved or consulted. | string | SWIM-SERV-010 Service standard reference | Rule Serv_Std: Optional when adherence. No use otherwise. | Optional | ||
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. | ||||||||
Document | --- | 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 | 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). | Mandatory | ||
SWIM-SERV-026 Model view | Guidance: Provide at least a document with type INFORMATION_DEFINITION | |||||||
SWIM-SERV-029 Examples of code | See as well Guidance on serviceDocument. | |||||||
Document | documentType | The type of document. | CodeDocumentType | multiple | Guidance: Select the code according to usage described in Code Lists walk-through. | Mandatory | ||
Document | title | The name by which the document is formally known. [SWIM-SERV-005;SWIM-SERV-010] | string | multiple | Mandatory, minLength=5 | |||
Document | version | The current version or revision level of the document. | string | multiple | Guidance: in absence of a version, consider providing a reference date. | Mandatory, minLength=1 | ||
Document | description | The description of the document. | string | multiple | Guidance for SERVICE_MODEL: declare the notation used to express the model view | Optional | ||
SWIM-SERV-026 Model view | ||||||||
Document | reference | An external reference at which the document can be retrieved or consulted. | string | multiple | Guidance: in absence of an external reference, leave empty. Later on, Registry may help providing a reference. | Optional |
Version
0.0.3
Document Categories
Services
Image
