Working towards the next version of the SWIM Supporting Material

Page tree

Versions Compared

Key

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

Guidance starting from the schema structure


Object under assessment

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

Legend

Expand
titleLegend [+]
Rows

each row represents an attribute or a type of the schema

    attributes are in white background

    types are in light blue background

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

    this order could become standard practice for JSON service descriptions


Columns1st = row number



1/ derived from the schema

col = name of the type

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

col = description of the element (type or attribute)

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



2/ "guidance"

col = trace and link to the requirement(s)

col = guideline to help in using this type / attribute



3/ "rule"

col = rule for COMPLIANT case

col L = rule for CANDIDATE case 

col M = rule for DEFINITION case 

     "same" means the compliant rule applies 
Panel
borderColorlightgrey

Table of Contents

Walk-through

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

0101010104510791010201203013010125060555555013606067065656510012546211201200114014001215015020221021034123300300130310310101500234650089105401340550550301236006006008610610234566206206802012012810481082023820820
1type sortattr sortElement NameAttribute NameDescriptionAttribute TypeRequirement infostatusCommentGuidelineCOMP RuleCAND ruleDEFN Rule
20---informationServiceThe description of a service.[SWIM-SERV-001]InformationServiceSWIM-SERV-001 Description coverageFRNote: this row was initially missingRationale: The readability of a service description is improved by keeping it focussed on one service.Mandatorysamesame
30InformationService---A type of service that provides an ATM information sharing capability.---SWIM-SERV-001 Description coverageFRDescr=Description of an  information serviceGuidance: Describe here your prospective service, operational service or service definition.(M)samesame
41InformationServicedescriptionInformationA container for Service Description metadata.DescriptionInformationmultipleFR2Descr=metadata about the description.Note: This information is about the document  more than the underlying service.Mandatorysamesame
52InformationServicenameA piece of identifying information that gives stakeholders a way to reference or identify a service. [SWIM-SERV-006]stringSWIM-SERV-006 Service identificationFR2Evolution: Move to type ServiceIdentification with name & version as attributes.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=1samesame
63InformationServiceversionThe version of the information service. [SWIM-SERV-006]stringSWIM-SERV-006 Service identificationFR2Evolution: Move to type ServiceIdentification with name & version as attributes.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=1samesame
710InformationServiceserviceAbstractA brief summary of the service offering. [SWIM-SERV-007]stringSWIM-SERV-007 Service abstractFR3

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

Guidance: Include or introduce:

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

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

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

SWIM-SERV-009 Service categories

SWIM-REG-0004 Service categorization

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

1310InformationServiceserviceInterfaceThe means by which the underlying capabilities of a service are accessed.InterfacemultipleFR5

Guidance: Describe one or more interfaces.

Provide all interfaces: provider side and consumer side interfaces.

Mandatory, minItems=1

1411InformationServiceserviceDescriptionReferencesA container for references to documents describing specific aspects of the service instance.ServiceDescriptionReferencesmultipleFR7
Mandatory

150DescriptionInformation---Information identifying the service description.---multipleFR3Descr=Meta information about the service description.Note: This groups information specific to the service description, and not about the underlying service.(M)samesame
1620DescriptionInformationserviceDescriptionIdentificationInformation identifying the service description.ServiceDescriptionSWIM-SERV-005 Description identificationFR
Mandatorysamesame
172DescriptionInformationabbreviationsAbbreviations or acronyms used by the service description.AbbreviationSWIM-SERV-003 Define abbreviationsFRGuidance: Define all abbreviations and acronyms used in the description. Unless they are systematically made explicit, such as in "IFR (Instrument Flight Rules)".Mandatory, minItems=0samesame
180ServiceDescription---Information needed in order to use, or consider using, a service.---SWIM-SERV-005 Description identificationFR2

Name=DescriptionIdentification

Descr=Information that supports the identification and citation of a service description
Rationale: supports the identification and citation of a service description.(M)samesame
1930ServiceDescriptionserviceDescriptionTitleThe name by which the document is formally known. [SWIM-SERV-005;SWIM-SERV-010]stringSWIM-SERV-005 Description identificationFR2Name=title
Mandatory, minLength=5samesame
20302ServiceDescriptionserviceDescriptionEditionManifestations of a publication embodying essentially the same content. [SWIM-SERV-005]stringSWIM-SERV-005 Description identificationFR2Name=edition;
Descr=The edition of the document 
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=1samesame
2130ServiceDescriptionserviceDescription ReferenceDateThe date at which the document has been published. [SWIM-SERV-005]stringSWIM-SERV-005 Description identificationFR2

Name=referenceDate

Descr=a reference date for use in citing the service description 


Mandatory, format is "yyyy-mm-dd"samesame
2240Abbreviation---An abbreviation or acronym used by the service description. [SWIM-SERV-003]---SWIM-SERV-003 Define abbreviationsFR2

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

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

The abbreviated form eg "IFR".

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

Mandatory, minLength=1samesame
24402AbbreviationdescriptionThe description of the abbreviation.stringSWIM-SERV-003 Define abbreviationsFRThe term in full lenth eg "Instrument Flight Rules". Verification: Check if the term exists in AIRM and is abbreviated, verify the abbreviation is the same.Mandatory, minLength=5samesame
2550ServiceProvision---Description of who provides the service, when and how it is supported.---SWIM-SERV-008 Service providerFREvolution: if providerType and dateInOperation are moved out (see comments), consider renaming to ServiceProvider. See ServiceProvider.
(M)

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

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

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

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

Mandatory, minLength=5

283ServiceProvisionproviderTypeThe type of service provider.CodeStakeholderType

SWIM-SERV-009 Service categories

FRUnclear use, except as a categorisation. In particular for DEFN, for which there is no notion of provision. Thus move to ServiceCategorisation.Mandatory, minItems=129504



Mandatory, minItems=1

29ServiceProvisiondateInOperationDate at which the service went into operation or is planned to become operational.stringSvcOvwFR6Question: about use for dates in the future… Evolution: Consider moving this info close to Lifecycle!

Provide the date at which this service version became operational.

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

Mandatory, format is "yyyy-mm-dd"

30505ServiceProvisionserviceSupportProvision of material and guidance necessary for the use of the information service.stringSvcOvwFRNeed make clear what the content is. Eg see discrepancy between Descr and Guidance

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

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

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

3255PointOfContact---A person or group within an organization, suitable for making a human contact for any purpose. [SWIM-SERV-008]---SWIM-SERV-008 Service providerFRQuestion: Why human contact? This can be a URL. URL and postal address are missing: consider adding bothGuidance: At least one contact information is Guidance: At least one contact information is required. Example contact information: email address; postal address; phone number; URL.
Example points of contact: “Customer Relations, to request access to the service, http://www.donlon-airport.com/swim/service-request”; “Service Desk, to report incidents on services in operation, contact [24/7] +693 555 01 service-desk@donlon-airport.com”.
(M)

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

342PointOfContactdescriptionThe description of the point of contact.stringSWIM-SERV-008 Service providerFR2Name=role (as in the spec.) or function (as in SvcOvw);

Desc=The role of the point of contact

Describe the role / function of the point of contact. When applicable add contact info such as URL link or postal address.Mandatory, minLength=5

353PointOfContactemailAn electronic mail address used to correspond in writing with the point of contact.stringSWIM-SERV-008 Service providerFR2Proposed evolution: see Schema evolution#ContactInfoGuidance: At least one contact information is required.Optional

364PointOfContactphoneNumberA telephone number used to communicate orally with the point of contact.stringSWIM-SERV-008 Service providerFR2Proposed evolution: seeSchema evolution#ContactInfoGuidance: At least one contact information is required.Optional

3760ServiceCategorisation---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 categoriesFRRationale: Service category information allows discovering services by a series of classification criteria. (M)samesame
3860ServiceCategorisationserviceTypeAn indication of the status of the service with regard to SWIM Service conformance.CodeSWIMService ConformanceStatusType

SWIM-REG-0004 Service categorization

FR7Evolution: Consider splitting the field, separating the notion of Type (instance or definition) from the notion of compliance status.Guidance: Select a code as Guidance: Select a code as indicated in Code Lists walk-through.Mandatorysamesame
39602ServiceCategorisationlifeCycleStageA classification of services based on their current, past, or future availability for provisioning. [SWIM-SERV-009]CodeLifeCycleStepType

SWIM-REG-0004 Service categorization

FR

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)
4060ServiceCategorisationbusinessActivityTypeThe type of business activity.CodeBusinessActivityType

SWIM-REG-0004 Service categorization

FR

Select one or more code valuesMandatory, minItems=1

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

SWIM-REG-0004 Service categorization

FR

Select one or more code values

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

Mandatory, minItems=1

425ServiceCategorisationinformationCategoryTBDCodeInformationExchangeCategory

SWIM-SERV-009 Service categories

FR

Descr=information exchange area as defined in PCP.Select one or more code valuesMandatory, minItems=1

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

SWIM-SERV-017 Message exchange pattern

FR(lightbulb)The MEP identification document would benefit from being aligned to values of the CodeApplicationMessageExchangeType (eg on "ONE_WAY", probably more)

Select one or more code values.

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

Mandatory, minItems=1

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

SWIM-REG-0004 Service categorization

FR3

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

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

Optional

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

SWIM-REG-0004 Service categorization

SERV-OVW-008 Geographical extent

FRConsider an additional field to define or complement the geographical extent textually (eg thru a polygon). Consider adding a list of ICAO Regions (as in SvcOvw). See Schema evolution#GeographicalExtent

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

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

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

SWIM-REG-0004 Service categorization

FR2Consider simplfying the name to countryCode

List zero or more code values.  Applicable values are in ICAO doc 7910.Optionalsamesame
472GeographicalExtentfirICAOLocationIndicatorA 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

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

SWIM-REG-0004 Service categorization

FR2Consider simplfying the name to aerodrome.

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

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

Rationale: Operational needs relate to the operational context in which the service is used. IERs reference the requirements that are at the origin of the service. This information supports decision making in terms of service suitability within a particular operational context.

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

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

Rationale: The functions provide business and operational experts with a business view of the interactions with the service, without having to look at the interface details.

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

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

Rationale: This requirement ensures that a service consumer is aware of any
limitations on the access and use of the service.
It is good practice to share business constraint information associated with the conditions of usage of the service.

Mandatory, minItems=1

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

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

Rationale: This is a key criterion in deciding to use the service. This is key information to be included in a service level agreement and will influence the content of the SLA. It informs contract negotiations between consumers and providers.

Mandatory, minItems=3

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

SWIM-SERV-ADD Additional info

SWIM-SERV-024 Filter capabilities

SERV-OVW-008 Geographical extent        

SERV-OVW-017 Sources of information

FR9

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

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

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



Optional, minItems=0samesame
55100ServiceGeneralDescriptionvalidationActivity whereby a service is checked for conformance with the service objectives and requirements. [SWIM-SERV-027]ValidationOfServiceSWIM-SERV-027 Service validationFR3List one or more validation activities.Mandatory, minItems=1
Optional
561100OperationalNeed---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 needsFR3

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

Guidance:

  • include information about the operational needs fulfilled by the service;
  • indicate whether information exchange requirements (IER) were used in the identification of the needs for the service; and if so
  • include or refer to the information exchange requirements (IER).
  • indicate relationship to PCP and/or SESAR Deployment Plan

Rationale: Operational needs relate to the operational context in which the service is used. IERs reference the requirements that are at the origin of the service.

(M)samesame
571101OperationalNeednameThe name of the operational requirement.stringSWIM-SERV-011 Operational needsFR3Guidance: provide a short name for the operational needMandatorysamesame
58110OperationalNeeddescriptionDescription of the operational needs fulfilled by the service. Includes or refers to information exchange requirements [SWIM-SERV-011].stringSWIM-SERV-011 Operational needsFR3

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

Make explicit the needs addressed by the service.

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

Mandatorysamesame
591200Functionality---A type of activity describing the functionality of a service.---SWIM-SERV-012 Service functionalityFR3





(M)samesame
60120FunctionalitynameThe name of the service function.stringSWIM-SERV-012 Service functionalityFR3Provide a short name for the service functionMandatory, minLength=1samesame
612FunctionalitydescriptionDescription of the service function. [SWIM-SERV-012]stringSWIM-SERV-012 Service functionalityFR3

Describe here the service function.

Note: A function is a type of activity describing the functionality of a service. Every function usually (but not always) can be mapped to service operations defined as a part of the service’s interface; i.e., functions provide a “business view” and service operations provide a “technical view” of a particular service activity.

Mandatory, minLength=5samesame
623FunctionalityrealWorldEffectAn ultimate purpose associated with the interaction with the service. It may be the response to a request for information or the change in the state of some entities shared between the participants in the interaction. [SWIM-SERV-012]stringSWIM-SERV-012 Service functionalityFR3Question: Where is the description text coming from?

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

Note: A real world effect is an ultimate purpose associated with the interaction with the service. It may be the response to a request for information or the change in the state of some entities shared
between the participants in the interaction.

Mandatory, minLength=0samesame
63140AccessAndUseCondition---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 conditionsFR3
(M)

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

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

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

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

Note: the SD spec includes examples of such conditions.

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

Mandatory, minLength=5

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

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

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

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

Mandatory, minLength=5

69130QualityOfServicedescriptionDescription of the quality of service offered with regards to: 1)availability of the service; 2)response time of the service; and 3)throughput of the service (SWIM-SERV-014). It also describes less quantitative aspects suchs as 4)integrity, 5)confidentiality and possibly any other service related qualities defined in ISO 25010stringSWIM-SERV-014 Quality of serviceFR3Note: Desc could be shortened, as part of it could be moved to guidance (see name)See Notes / Examples of the requirement.Mandatory, See Notes / Examples of the requirement.Mandatory, minLength=5

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

SWIM-SERV-ADD Additional info

SWIM-SERV-024 Filter capabilities

SERV-OVW-008 Geographical extent   

SERV-OVW-017 Sources of information    

FR4

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

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

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

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

SWIM-SERV-ADD Additional info

FR9

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

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

Mandatory, minLength=5

72150ConceptdescriptionDescription of the concept.string

SWIM-SERV-ADD Additional info

FR4Provide the description.Mandatory, minLength=5

73160ValidationOfService---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 validationFR3

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

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

(M)

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

SvcOvw

SWIM-SERV-027 Service validation

FR3

Evolution: Missing a value for "not validated yet" (see Code Lists walk-through).

Descr: The validation method usedName: Consider renaming type to method. (In addition (consider renaming type as well CodeValidationMethodType)

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

Note: Is mandatory except for the case not validated.

Optional

751602ValidationOfServicedescriptionValidationOfServicedescriptionThe description of the service validation. [SWIM-SERV-027]stringSWIM-SERV-027 Service validationFR3

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

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

Mandatory

762000ServiceInformationDescription---A container for the description of the information exchanged by the information service.---multipleFR9

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

Guidance: SWIM-SERV-022 Information definition requires a description of the elements of the exchanged information. This is provided here. It can be provided by reference and can make use of a published information exchange model. Therefore, use the option best suited to your service.

(M)(M)(M)
772001ServiceInformationDescriptioninformationDefinitionA formal representation of information concepts or data concepts. [SWIM-SERV-022]InformationDefinitionSWIM-SERV-022 Information definitionFR8Rationale: Enables to understand the information provided by the service, with a specific focus to the semantics of the informationMandatoryMandatoryMandatory
78200ServiceInformationDescriptionexchangeSchemaFormal description of the data involved in an information exchange.ExchangeSchemaSWIM-SERV-019 Protocols and data formatFR9

List the data formats used.

MandatoryOptionalOptional
792100InformationDefinition---A formal representation of information concepts or data concepts. [SWIM-SERV-022]---SWIM-SERV-022 Information definitionFR8Rationale: Enables to understand the information provided by the service, with a specific focus to the semantics of the information(M)(M)(M)
801InformationDefinitionnameThe name of the Information Definition. [SWIM-SERV-022]stringSWIM-SERV-022 Information definitionFR8Guidance: 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 DefinitionMandatoryMandatoryMandatory
812InformationDefinitiondescriptionThe description of the Information Definition. [SWIM-SERV-022]stringSWIM-SERV-022 Information definitionFR8

Guidance: introduce this information definition. Eg use the information definition abstract SWIM-INFO-005 Information definition scope.

Guidance: Make sure to have one or several service documents with type INFORMATION_DEFINITION. See Guidance on serviceDocument.

MandatoryOptionalOptional
82210InformationDefinitionairmConformantAn indication whether the information definition used by the service conforms to the ATM Information Reference Model. [SWIM-SERV-023]booleanSWIM-SERV-023 AIRM conformanceFR8

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


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

Rule: Mandatory when airmConformant is true. No use otherwise.

Guidance: Version of the AIRM that was used to establish semantic correspondence.

Whether stand-alone or integrated, make sure the semantic correspondence is made available in a service document with type INFORMATION_DEFINITION.


Conditional MandatoryOptionalsame
842200ExchangeSchema---Formal description of the data involved in an information exchange.---SWIM-SERV-019 Protocols and data formatFR9Question: how far is this covering the requirement SWIM-SERV-020 Machine-readable interface as well?Rationale: Enables to understand data format(s).(M)(M)(O)
85220ExchangeSchemanameThe name of the exchange schema. [SWIM-SERV-019]stringSWIM-SERV-019 Protocols and data formatFR9Guidance: Provide the name of the data format that is used to exchange data via the service interface.MandatoryMandatoryMandatory
86220ExchangeSchemaschemaLanguageDescription of the language used (e.g. XML, JSON). [SWIM-SERV-019]stringSWIM-SERV-019 Protocols and data formatFR9Guidance: Indicate the language in which the data format is expressed (e.g. XSD, JSON, natural language,..)MandatoryOptionalOptional
87220ExchangeSchemareferenceA reference to the exchange schema containing the specifications of the data structures.stringSWIM-SERV-019 Protocols and data formatFR9Question: Is this not redundant with service documents of type MACHINE_READABLE_SERVICE_DESCRIPTION? see Guidance on serviceDocument. ==> made Optional. Ok?Guidance: Indicate with a reference the Guidance: Indicate with a reference the location of where the data format is defined (e.g. See service documents)OptionalOptionalOptional
880ServiceTechnicalDescription---Description of the technical aspects of the service including data structures, interface and operations behaviour, security mechanisms and technical constraints---multipleFR5Note: It may be possible that this results in an empty object.(M)

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

Rationale: Knowing and satisfying the pre-requisite constraints of a service facilitate good use of the service, such as benefiting from the indicated quality of service statements.It also supports decision making in terms of assessing the implication, costs and feasibility, of using the service.

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

Guidance: Describe zero or more technical constraints.

Optional, minItems=0samesame
90300ServiceTechnicalDescriptionsecurityMechanismA process (or a device incorporating such a process) that is utilized or implemented by the service in order to address a security threat.SecurityMechanismSWIM-SERV-019 Protocols and data formatFR9Evolution: Capture the full list of protocols in a more structured way, integrating this list.

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

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

Optional, minItems=0

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


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


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

Conditional MandaotryOptionalOptional
92310SecurityMechanism---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 formatFR6

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

See as well Interface.interfaceBindingDescription

(M)

932SecurityMechanismnameThe name of the security mechanism.stringSWIM-SERV-019 Protocols and data formatFR9

Provide the name and version of the protocol.

Eg X.509v3 Client Certificate

Mandatory

943SecurityMechanismdescriptionThe description of the security mechanism.stringSWIM-SERV-019 Protocols and data formatFR9

Describe the mechanism

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

Mandatory

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

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

Note: Mandatory when existing.

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

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

983302TechnicalConstraintdescriptionTechnicalConstraintdescriptionThe description of the technical constraint. [SWIM-SERV-015]stringSWIM-SERV-015 Technical constraintFR5Guidance: describe the technical constraint.Mandatory, minLength=5

993400ServiceMonitoring---Tracking state and operational conditions related to the execution, performance, and real-world effects of services.---SWIM-SERV-028 Service monitoringFR5Note: Mandatory when available.(O)samesame
1003401ServiceMonitoringmonitoringDescriptionDescription if available of the existing monitoring capabilities and how this can be used by the consumer. [SWIM-SERV-028].stringSWIM-SERV-028 Service monitoringFR5Evolution suggestion: the structure would benefit from being aligned and/or simplified. Eg Why monitoringDescription rather than description as usual? Why 2 fields for 1 string?Guidance: provide the description so that the mechanism can be used by the consumer.Mandatory, minLength=5

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

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

(M)

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

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

104500InterfaceinterfaceProvisionSideAn indication that the interface is a provider side interface or a consumer side interface. [SWIM-SERV-016]CodeInterfaceSideTypeSWIM-SERV-016 Service interfacesFR5Question: the TI profile and version is imbedded inside the code value (eg TI_YP_1_0). Is that good enough?Guidance: select the appropriate value.Mandatory

105500InterfacetiPrimitive MessageExchangePatternThe type of primitive MEP implemented by the interface.CodePrimitive MessageExchangePatternTypeN/AFR5Question: To which requirement should this be linked? (a requirement is needed, as the field is mandatory)

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

Guidance: select the appropriate value.

Mandatory

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

Rationale: To support the concept of interoperability between the service provider and service consumer, the SWIM TI Profiles only allow a certain set of technical solutions, which can be chosen by the service designer.

Guidance: select the appropriate code value.

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

Mandatory

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

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

SWIM-SERV-018 TI Profile and bindings

SWIM-SERV-019 Protocols and data format

FR9

Evolution: split the field, to separate information for each requirement (easier for readers and for guidance).

Evolution: the list of protocols will become more structure (similar as for security mechanisms).

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

Guidance: Provide here a textual description of

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

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

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

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

Mandatory, minItems=1

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

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

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

Mandatory, minItems=1

111500InterfacebehaviourThe manner in which a service operates under normal and unexpected conditions. [SWIM-SERV-025]ServiceBehaviourSWIM-SERV-025 Service behaviourFR7Evolution: check consequence if behaviour is moved up a level. PEDRO FERNANDEZ SANCHO

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

Guidance: provide one or more behaviours.

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

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

Mandatory, minItems=1

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

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

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

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

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

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

OptionalOptionalNA
117550Resource---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/AFR8

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

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

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

(O)(O)NA
1181ResourcetypeThe type of resource.CodeTechnicalResourceTypeN/AFR8Rationale: Indicates the type of the resource: QUEUE, TOPIC,..OptionalOptionalNA
1192ResourcenameThe name of the resource.stringN/AFR8Guidance: provide a self descriptive nameMandatoryMandatoryNA
120550ResourcedescriptionThe description of the resource.stringN/AFR8Guidance: Consider providing additional information that enables to understand the resource ( E.g. For QUEUE the behavior FIFO)OptionalOptionalNA
121600Operation---Specification of a transformation or query that an object may be called to execute.---SWIM-SERV-021 Service operationsFR7Guidance: provide a technical description of a service operation(M)

122600OperationnameThe name of the operation. [SWIM-SERV-021]stringSWIM-SERV-021 Service operationsFR7

Guidance: Provide the name of the operation.

Note: For readability and understanding of services implemented using REST methods, it is best practice to define logical operations and to map these to the underlying REST methods being used.

Mandatory

123600OperationdescriptionThe description of the operation.stringSWIM-SERV-021 Service operationsFR7Guidance: Provide a description of the intent and the results of the service operation; andMandatory

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

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

1266OperationtiProtocolMethodA protocol method used to implement the operation.stringSWIM-SERV-021 Service operationsFR7Question: Why is this an array?

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

Example: HTTP GET, HTTP POST.

Optional, minItems=0


1275OperationpreconditionA description of the state or condition that should be true before the operation can proceed.stringSWIM-SERV-021 Service operationsFR7

Question: Why a single string?

Evolution: Would it be a good idea to integrate in processingConsideration array? Eg with name = "precondition".

Guidance: Describe the pre-condition(s) to execute the operation.Optional

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

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

This may be expressed as business rule.

Optional, minItems=0

1296007OperationoperationMessageA message associated with the operation. [SWIM-SERV-021]MessageSWIM-SERV-021 Service operationsFR7

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

Mandatory, minItems=1

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

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

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

Guidance: Provide the name of the message.

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

MandatoryMandatoryMandatory
133610MessagedescriptionThe description of the message.stringSWIM-SERV-021 Service operationsFR7

Guidance: Optionally provide a description of the message.

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

OptionalOptionalOptional
134610MessageisFaultAn indication whether the message is a fault or not. [SWIM-SERV-021]booleanSWIM-SERV-021 Service operationsFR7Guidance: Optionally indicate whether the message is an error message.OptionalOptionalOptional
135610MessageheadersThe description of the headers.stringSWIM-SERV-021 Service operationsFR8Guidance: Consider providing indication of those headers that are important for processing the message (E.g. Content Type XML, JSON, Content Enconding GZIP,..)OptionalOptionalOptional
136610MessagebodyThe description of the body.stringSWIM-SERV-021 Service operationsFR8Guidance: Consider indicating the detailed structure of the payload. E.g. AIXM_v.5.1.1.AIXM.AIXM Features.AirportHeliport.Airport/HeliportOptionalOptionalOptional
1370ProcessingConsideration---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 operationsFR8Guidance: Consider indicating all constraints that further qualify a service operation (e.g. It does not accept request for a date in the past, or an update that is too close to the current value, or a certain frequency of request).(O)(O)(O)
1381ProcessingConsiderationnameThe name of the processing consideration.stringSWIM-SERV-021 Service operationsFR8Guidance. Provide a self descriptive name.MandatoryMandatoryMandatory
1396202ProcessingConsiderationdescriptionThe description of the processing consideration.stringSWIM-SERV-021 Service operationsFR8Guidance. 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

1400ServiceBehaviour---The manner in which a service operates under normal and unexpected conditions. [SWIM-SERV-025]---SWIM-SERV-025 Service behaviourFR7Evolution: Consider making the SERVICE_BEHAVIOUR_DESCRIPTION document close to this information.

Examples of behaviour specification:

  • The behaviour under normal conditions;
  • The behaviour with incorrect input data (e.g., out of range or incorrect data type);
  • The use of error messages, and error handling in general;
  • The list of error codes and expected effects.


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

Note: The service behaviour can be captured in formal modelling notations such as a Unified Modeling Language (UML) sequence diagram, and/or expressed as textual description in plain language.

(M)

1416801ServiceBehaviournameThe name of the service behaviour. [SWIM-SERV-025]stringSWIM-SERV-025 Service behaviourFR7Guidance: provide a short name for the behaviourMandatory

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

Guidance:

Describe the behaviour as

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

And / or make reference to a SERVICE_BEHAVIOUR_DESCRIPTION document.

Mandatory

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

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

SWIM-SERV-010 Service standard reference

FR6

Evolution: Split the field to separate adherence to a service standard from conformance to SWIM specifications.

Action: identify and add requirement for the SWIM spec conformance. Once this is done, the walk-through can be revisited.


Guidance: use this list for

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

145800ServiceDescriptionReferencesserviceDocumentA document that relates to the information service.DocumentmultipleFR7Evolution: Consider to split out this field, so that document info is closer to related info. Keeping in mind that registry could provide a view on the documents.

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

Mandatory, minItems=1

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

SWIM-SERV-010 Service standard reference

FR7

Note: validation changes in schema 3f.

Note: this type mixes 2 different concepts: Adherence to a service standard and conformance to the SWIM specs.

Decision needed: Decide whether conformance to SWIM specs is to be kept in serv descr (disc for Reg CCB). If yes, formalise the need as a requirement.

Evolution: Remove conformance or separate it from service standard, depending on decision above.


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

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

Rule Serv_std: Mandatory

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

Rule SWIM_spec: Optional.

(M)

147810ImplementedStandardstandardTypeThe type of implemented standard.CodeServiceStandardTypeSWIM-SERV-010 Service standard referenceFR7

Guidance Serv_Std: Select code SERVICE_STANDARD.

Guidance SWIM_spec: Select code of the concerned SWIM spec.

Mandatory

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

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

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

Mandatory

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

Rule Serv_Std: Mandatory when adherence. No use otherwise.

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

Rule SWIM_spec: Optional (no added value)

Conditional

(Optional in Schema)



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

Rule Serv_Std: Mandatory when adherence. No use otherwise.

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

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

Conditional

(Optional in Schema)



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

Evolution: Rename to optionsAndDeviations.

Description: a statement on any implemented options or deviation from the standard.

Rule Serv_Std: Optional when adherence. No use otherwise.

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

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

Conditional

(Optional in Schema)



1526ImplementedStandarddescriptionThe description of the entity.stringSWIM-SERV-010 Service standard referenceFR7

Rule Serv_Std: Optional when adherence. No use otherwise.

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

Guidance SWIM_spec: leave empty.

Optional

1538107ImplementedStandardreferenceAn external reference at which the standard can be retrieved or consulted.stringSWIM-SERV-010 Service standard referenceFR7Note: Use this field rather than the document with code SERVICE_STANDARD.010 Service standard reference

Rule Serv_Std: Optional when adherence. No use otherwise.

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

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

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

Optional

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

SWIM-SERV-020 Machine-readable interface 

SWIM-SERV-026 Model view

SWIM-SERV-029 Examples of code  

FR6

Note: difficult to trace to all requirements. A tentative tracing to the requirements is done per documentType (see Code Lists walk-through).

Note: some requirements use this type only (these are the ones mentioned on the left), the others being SWIM-SERV-013 Access and use conditions, SWIM-SERV-014 Quality of service, SWIM-SERV-019 Protocols and data format, SWIM-SERV-022 Information definition, SWIM-SERV-025 Service behaviour.interface 

SWIM-SERV-026 Model view

SWIM-SERV-029 Examples of code  

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

Guidance: Provide at least a document with type INFORMATION_DEFINITION

See as well Guidance on serviceDocument.

(M)

1551DocumentdocumentTypeThe type of document.CodeDocumentTypemultipleFR7

Evolution: Consider adding value OTHER. Consider removing MESSAGE_EXAMPLE, SERVICE_SPECIFICATION and SERVICE_CERTIFICATION. See Code Lists walk-through.

Evolution: consider being able to tag a document by several types (as for type of security mechanism) because one document can be used for several purposes

Guidance: Select the code according to usage described in Code Lists walk-through.Mandatory

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

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


1585DocumentdescriptionThe description of the document.string

multiple

SWIM-SERV-026 Model view

FR7

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

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