Ongoing discussions within the SWIM communities of interest

Page tree

Ongoing discussions within the SWIM communities of interest

Skip to end of metadata
Go to start of metadata

This is the list possible of change requests created by SSCONE. They would lead to an evolution of the JSON registry schema.





ServiceIdentification- new attribute and type

name

ServiceIdentification

justification

This change would bring the schema into better alignment with SWIM-SERV-006 Service identification of the SWIM Service Description Specification. It is desirable to keep the service name and version closely related.

description

In InformationService:

  • delete the existing name and version attributes
  • create a new mandatory attribute serviceIdentification of type ServiceIdentification
  • the ServiceIdentification type contains the attributes name and version
statusagreed by SSCONE
impact

This is a structural change (change of grouping). The information is exactly the same.

 proposed schema +
		"ServiceIdentification": {
			"description": "Information for identifying the service.",
			"type": "object",
			"additionalProperties": false,
			"required": [
				"name", "version"
			],
			"properties": {
				"name": {
					"description": "A piece of identifying information that gives stakeholders a way to reference or identify a service. [SWIM-SERV-006]",
					"type": "string",
					"minLength": 1
				},
				"version": {
					"description": "The version of the information service. [SWIM-SERV-006]",
					"type": "string",
					"minLength": 1
				}
			}
		}
example
 example +
"serviceIdentification": {
      "name": "TargetOffBlockTimeSetting",
      "version": "1.0.0"
 }

ContactInformation - new type

name

ContactInformation

justification

This change would bring the schema into better alignment with SWIM-SERV-008 Service provider of the SWIM Service Description Specification by making contact information mandatory and covering a greater variety of types (eg URL and postal address).

At the moment the 2 optional attributes email and phoneNumber do not make clear that contact information is mandatory. They miss certain types of contact such as URL.


description

Within type PointOfContact:

  • delete attributes "email:string and phoneNumber: string"
  • create attribute "contactInformation: list of ContactInformation", (Mandatory, minItems=1).

Create new type ContactInformation, with attributes

  • type: enumeration (mandatory) values: EMAIL, URL, PHONE, POSTAL, OTHER
  • address: string (mandatory)
statusagreed by SSCONE
impact
 proposed schema +
		"PointOfContact": {
			"description": "List of persons or groups within the service provider organization, suitable for making a human contact for any purpose. [SWIM-SERV-008]",
			"type": "object",
			"additionalProperties": false,
			"required": [
				"name", "contactInformation", "role"
			],
			"properties": {
				"name": {
					"description": "The name of the point of contact. [SWIM-SERV-008]",
					"type": "string",
					"minLength": 1
				},
				"role": {
					"description": "The role of the point of contact. [SWIM-SERV-008]",
					"type": "string",
					"minLength": 5
				},
				"contactInformation": {
					"description": "Information used to correspond with the point of contact. [SWIM-SERV-008]",
					"type": "array",
					"items": {
						"$ref": "#/definitions/ContactInformation"
					}
				}
			}
		}

		"ContactInformation": {
			"description": "Information used to correspond with the point of contact. [SWIM-SERV-008]",
			"type": "object",
			"additionalProperties": false,
			"required": [
				"type", "address"
			],
			"properties": {
				"type": {
					"description": "The type of contact information. [SWIM-SERV-008]",
					"$ref": "#/definitions/CodeContactInformationType"
				},
				"address": {
					"description": "A phone number or an electronic mail address used to correspond with the point of contact. [SWIM-SERV-008]",
					"type": "string",
					"minLength": 1
				}
			}
		}
example
 current example +
"pointOfContact": [
        {
          "name": "access request",
          "description": "to request access to the service, use following link http://www.donlon-airport.com/swim/service-request",
          "email": "",
          "phoneNumber": ""
        },
        {
          "name": "service support",
          "description": "For any issues relate to the operation of the Donlon service",
          "email": "service-desk@donlon-airport.com",
          "phoneNumber": "+693 555 01"
        }
      ]
 updated example +
			"pointOfContact": [
				{
					"name": "access request",
					"role": "to request access to the service, use following link",
					"contactInformation": [
						{
							"type": "URL",
							"address": "http://www.donlon-airport.com/swim/service-request"
						}
					]
				},
				{
					"name": "service support",
					"role": "For any issues relate to the operation of the Donlon service",
					"contactInformation": [
						{
							"type": "EMAIL",
							"address": "service-desk@donlon-airport.com"
						},
						{
							"type": "PHONE",
							"address": "+693 555 01"
						}
					]
				}
			]

GeographicalExtent- updates

name

GeographicalExtent

justification

SWIM-SERV-009 Service categories outlines that it is a best practive to add categories. This helps e.g. discovery of services within a registry.

The service overview being prepared at ICAO requires a geographical extent - see SERV-OVW-008 Geographical extent.

description

Amend the type to cover the following

  • an additional field to define or complement the geographical extent textually (eg thru a polygon).
    • description (NEW string) Additional optional description of the geographical extent
    • this replaces the use of Concept with name = "Geographical extent"
  • an additional field to list the covered ICAO Regions (as in SvcOvw).
    • name = region (NEW list of codes)
    • type = CodeIcaoRegionType (see below)
    • description =
  • simplify the name of the existing fields
    • countryCode (renamed from stateICAONationalityLetters)
    • fir (renamed (from firICAOLocationIndicator)
    • aerodrome (renamed from aerodromeICAOLocationIndicator )

For each list of codes, indicate the applicable document for codification.

New CodeIcaoRegionType, with values AFI,ASIA, CAR, EUR, MID, NAM, NAT, PAC, SAM. (ICAO Doc 8144).

  1. AFRICA-INDIAN OCEAN (AFI) REGION;
  2. ASIA (ASIA) REGION;
  3. CARIBBEAN (CAR) REGION;
  4. EUROPEAN (EUR) REGION;
  5. MIDDLE EAST (MID) REGION;
  6. NORTH AMERICAN (NAM) REGION;
  7. NORTH ATLANTIC (NAT) REGION;
  8. PACIFIC (PAC) REGION; and
  9. SOUTH AMERICAN (SAM) REGION.
status

agreed by SSCONE

impact
 proposed schema+
		"GeographicalExtent": {
			"description": "The geographic coverage of the information provided by the service. [SWIM-REG-0004,SERV-OVW-008]",
			"type": "object",
			"additionalProperties": false,
			"properties": {
				"aerodrome": {
					"description": "A four-letter code group formulated in accordance with rules prescribed by ICAO and assigned to the aerodrome. [SWIM-REG-0004]",
					"type": "array",
					"items": {
						"type": "string"
					}
				},
				"fir": {
					"description": "A four-letter code group formulated in accordance with rules prescribed by ICAO and assigned to the airspace. [SWIM-REG-0004]",
					"type": "array",
					"items": {
						"type": "string"
					}
				},
				"countryCode": {
					"description": "Nationality letters of a State as defined by ICAO. [SWIM-REG-0004]",
					"type": "array",
					"items": {
						"type": "string"
					}
				},
				"description": {
					"description": "Additional optional description of the geographical extent.",
					"type": "string"
				},
				"region": {
					"description": "An ICAO region as defined in Appendix 1 to the Directives to Regional Air Navigation Meetings and Rules of Procedure for their Conduct (ICAO Doc 8-AN/874). [SERV-OVW-008]",
					"type": "array",
					"items": {
						"type": "string"
					}
				}
			}
		}


		"CodeICAORegionType": {
			"description": "The list of ICAO Regions as defined in Appendix 1 to the Directives to Regional Air Navigation Meetings and Rules of Procedure for their Conduct (ICAO Doc 8-AN/874).",
			"type": "string",
			"enum": [
				"AFI", "ASIA", "CAR", "EUR", "MID", "NAM", "NAT", "PAC", "SAM"
			]
		}
example

-

Filtering - new type

nameFiltering
justification

This change will fulfill requirement SWIM-SERV-024 Filter capabilities of the SWIM Service Description Specification.

The service overview being drafted at ICAO requires it. See Service Overview.

description

Need for an optional list of name, description.

  • structure name: Filtering? (FilteringAvailable? FilterCapabilities? )
  • structure location: serviceInformationDescription?

Example:

"filtering": {
"description" : "the filtering capabilities, including meaning and syntax of filter expressions, which can be applied to the information exchange [SWIM-SERV-024]",
"type" : "array",
"items" : { "$ref":"#/definitions/Filtering" },
"minItems": 0
}

"Filtering" : {
"description" : "a filtering capability, including meaning and syntax of filter expressions, which can be applied to the information exchange [SWIM-SERV-024]",
"type": "object",
"additionalProperties": false,
"required": ["name", "description"],
"properties": {
"name": {
"description" : "The name of the filtering capability. [SWIM-SERV-024]",
"type" : "string",
"minLength":1
} , {
"description" : "The description of the filtering capability. [SWIM-SERV-024]",
"type" : "string",
"minLength":5
}
}

statusagreed by SSCONE
impact
 proposed schema+
		"Filtering": {
			"description": "The filtering capabilities, including meaning and syntax of filter expressions, which can be applied to the information exchange. [SWIM-SERV-024]",
			"type": "object",
			"additionalProperties": false,
			"required": [
				"capability"
			],
			"properties": {
				"capability": {
					"description": "A filtering capability, including meaning and syntax of filter expressions, which can be applied to the information exchange [SWIM-SERV-024]",
					"type": "array",
					"items": {
						"$ref": "#/definitions/FilteringCapability"
					}
				}
			}
		}


		"FilteringCapability": {
			"description": "A filtering capability, including meaning and syntax of filter expressions, which can be applied to the information exchange [SWIM-SERV-024]",
			"type": "object",
			"additionalProperties": false,
			"required": [
				"name", "description"
			],
			"properties": {
				"name": {
					"description": "The name of the filtering capability. [SWIM-SERV-024]",
					"type": "string"
				},
				"description": {
					"description": "The description of the filtering capability. [SWIM-SERV-024]",
					"type": "string"
				}
			}
		}
example

-


Sources of information - new type

nameSource of information
justification

The service overview being drafted at ICAO requires it. See Service Overview - Sources of Information (optional field)

description

In type ServiceInformationDescription, add optional attribute sourcesOfInformation of type string.

  • description= A description of the origins of information provided by the service along with an indication whether there were any subsequent modifications
statusagreed by SSCONE
impact
example

SWIM spec TI YP 1.1 - new values

nameSWIM spec TI YP 1.1
justification

The publication of the new version of the SWIM TI spec requires a change in the enumerated values of type CodeServiceInterfaceBindingType.

The version of the TI spec is part of the enumerated values (see SWIM-SERV-018 TI Profile and bindings)

description

Below the newly required values:

    • "SWIM_TI_YP_1_1_WS_LIGHT",
    • "SWIM_TI_YP_1_1_WS_SOAP",
    • "SWIM_TI_YP_1_1_WS_SOAP_WITH_BASIC_MESSAGE_SECURITY",
    • "SWIM_TI_YP_1_1_WS_SOAP_WITH_MESSAGE_SECURITY",
    • "SWIM_TI_YP_1_1_WS_SOAP_WITH_FEDERATED_SECURITY",
    • "SWIM_TI_YP_1_1_WS-N_SOAP",
    • "SWIM_TI_YP_1_1_WS-N_SOAP_WITH_BASIC_MESSAGE_SECURITY",
    • "SWIM_TI_YP_1_1_WS-N_SOAP_WITH_MESSAGE_SECURITY",
    • "SWIM_TI_YP_1_1_WS-N_SOAP_WITH_FEDERATED_SECURITY",
    • "SWIM_TI_YP_1_1_AMQP_MESSAGING"

Question: should the old values be deleted?

statusagreed by SSCONE
impact

new values for type CodeServiceInterfaceBindingType

example
 example +
		"serviceInterface": [
			{
				"serviceInterfaceBinding": "SWIM_TI_YP_1_1_WS-N_SOAP"		


			} ]		

Service Behaviour - structure change

nameService Behaviour
justification

This change will ensure alignment with requirement SWIM-SERV-025 Service behaviour of the SWIM Service Description Specification that mentions service behaviour, not interface behaviour

description

Move the attribute "behaviour" from interface to service.

statusagreed by SSCONE
impact

Move attribute "behaviour" from Interface type to TechnicalDescription type.

example

-

Interface Protocols - structure change

nameInterface Protocols
justification

This change will ensure alignment with requirement SWIM-SERV-019 Protocols and data format of the SWIM Service Description Specification that requests the protocols per interface.

It will reduce complexity and avoid confusion by describing all service interface protocols in the same way, not distinguishing security protocols (see SecurityMechanisms) from other types (see interfaceBindingDescription).

description

Rename type SecurityMechanism to InterfaceProtocol.

  • description = ...

Remove attribute securityMechanism from ServiceTechnicalDescription.

Add attribute interfaceProtocol to ServiceInterface

  • Mandatory, array, minItems=1
  • type= InterfaceProtocol
  • description = ...
statusagreed by SSCONE
impact
Reorganisation of current content and addition of extra items.
example
 example +
		"serviceInterface": [
			{

				"interfaceProtocol": [
					{
						"name": "TLS 1.2",
						"description": "The service relies on TLS 1.2 to provide integrity and confidentiality.",
						"type": [
							"AUTHENTICATION",
							"CONFIDENTIALITY",
							"INTEGRITY"
						]
					},
					{
						"name": "Cypher Suites",
						"description": "The following cipher suites are allowed in accordance with ECRYPT-CSA recommendations https://www.ecrypt.eu.org/csa/documents/D5.4-FinalAlgKeySizeProt.pdf: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 , TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
						"type": [
							"AUTHENTICATION",
							"CONFIDENTIALITY",
							"INTEGRITY"
						]
					},
					{
						"name": "X.509v3 Server Certificate",
						"description": "The service utilizes X.509v3 public certificate to authenticate the provider.",
						"type": [
							"AUTHENTICATION"
						]
					},
					{
						"name": "X.509v3 Client Certificate",
						"description": "The service utilizes X.509v3 public certificate to authenticate the consumer.",
						"type": [
							"AUTHENTICATION"
						]
					}
				]


		}]


Attribute naming style - name changes

name

Attribute naming style

justification


In most cases, attribute names are kept short and to the point (Eg name, description, provider, businessActivityType).

However, in some cases the attribute name includes redundancy with the type name. 

  • Eg serviceDescriptionTitle, serviceDescriptionEdition, serviceDescriptionReferenceDate within serviceDescriptionIdentification, could easily be named title, edition, referenceDate. 

In some cases the attribute name is unnecessarily long:

  • Eg stateICAONationalityLetters, firICAOLocationIndicator, aerodromeICAOLocationIndicator within ServiceCategorisation, could easily be renamed countryCode, fir, aerodrome. (see GeoExtent)

Simplifying the names would make the schema easier to use.


description

Change names from current name to new name
current namenew name
serviceDescriptionIdentificationdescriptionIdentification
serviceGeneralDescriptiongeneralDescription
serviceInformationDescriptioninformationDescription
serviceTechnicalDescriptiontechnicalDescription
The complete list of proposed changes is available at the Schema walk-through
  • attribute name in bold: the comment column proposes an updated name (Name=...).
  • description in bold: the comment column proposes an updated description (Descr=...).
  • requirement in bold: the text in bold in the new / updated requirement link (to be added to the description). 

status

agreed by SSCONE

impact

-

example

-

Service Provider - name change

nameService Provider
justification

Requirement SWIM-SERV-008 Service provider of the SWIM Service Description Specification uses the term "service provider". This was called "service provision" in the schema. This has caused confusion and should be corrected.

description

change name for of attribute serviceprovision to serviceProvider

change name of type ServiceProvision to ServiceProvider

moving dateInOperation close to lifecycle attribute

statusagreed by SSCONE
impact-
example-

Ordering of fields

nameOrdering of fields
justification

The Schema walk-through identified a "logical" ordering of field. Adopting this ordering in JSON service descriptions brings additional harmonisation between service descriptions.

description

Adopted the order used in the schema walk through.

Ensure this is the order used by the registry export function.

statusagreed by SSCONE
impact
-
example-



  • No labels