Registry Data Structure

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 email 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