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
Assessment of Registry JSON Schema ed 0.3 21/01/20 for conformance with Service Description specification.

Object under Assessment

SWIMRegistrySchema_v0.0.3.json, as used by the SWIM Registry application for uploading / downloading Registry Entries. 

Assessment Objectives

namedescription
conformance to SD specassess whether the schema allows to produce a SD satisfying the requirements of the SD spec
trace to SD specmap between spec requirements and schema fields (as the structure and naming may diverge from the spec or the supporting material)
aligment with supporting materialassess how far the schema allows to satisfy the supporting material in the SD handbook

Note that alignment with SIR and supporting material have not started yet.

Assessment considerations

use for SD validation

Elements in the Schema are optional, so that the Schema cannot be used to validate a JSON doc (almost any JSON doc is valid).

The SWIM Registry validates a JSON doc with business rules within the application.

structure, grouping, naming

Mapping between schema structure and req could be improved.

There's a need to explain and/or restructure.

Unclear why some arrays have minItems = 1 for an optional field. When not filled in (yet) the field has to be removed, instead of remaining with an empty array.

external documents

The use of external documents need be clarified. In general and in relation to other fields (eg model, behaviour, information definition).

Can some of these documents be a part of the service description?

diagramsHow are diagrams be provided? Only through an external document?


Overall Assessment - NOT CONFORM

req countstatusstatus description
26(tick)requirement satisfied
1(error)requirement not satisfied
1(question)unclear status, need more info
1tbdnot assessed yet

Detailed assessment

Requirementlevelstatusreference / comment
General Requirements

 



SWIM-SERV-001 Description coverage

M

(tick)

Map: field informationService is the entry point. The field is not mapped to the requirement.


SWIM-SERV-002 Description language

M

tbd(not assessed yet) The checking will be about the use of UK English within the schema, in particular for field names and guidance text.
SWIM-SERV-003 Define abbreviations

M

(tick)

Map: fields name, description in abbreviations. Fields map to requirement (except description).

SWIM-SERV-004 Use standard abbreviations

R

(tick)

(no assessment to be done)

SWIM-SERV-005 Description identification

M

(tick)

Map: fields Title, Edition, ReferenceDate in ServiceDescriptionIdentification. Fields map to requirement.


SWIM-SERV-006 Service identification

M

(tick)Map: fields name and version within Information Service. Fields map to req.
SWIM-SERV-007 Service abstract

M

(tick)Map: field abstract within Information Service. Field maps to req.
SWIM-SERV-008 Service provider

M

(tick)

Map: fields provider, providerDescription, pointsOfContact within ServiceProvision. Fields map to req.

Within Point of Contact:

  • unclear how to put a URL or postal address.
  • (lightbulb)Consider rename field description to role, in alignment with req.

Within Service Provision, there are additional fields with unclear use.

  • field Service Support "Provision of material and guidance necessary for the use of the information service".
    • It is unclear what this is supposed to be containing.
    • (question) Is this related to Service Overview's field Support Availability "An overview of whether any service support may be offered to consumers"?
    • (lightbulb) If not clarified, consider removing.
  • field Date in Operation:
    • guidance needs to be more specific if this is for the service or the service version.
    • for a date in the future it is unclear what happens when the date is reached.
  • field Provider Type:
    • Use not clear. Should this be considered as a service category?
SWIM-SERV-009 Service categories

M

(tick)

Map: field informationCategory within serviceCategorisation. No definition. No map to req.

(lightbulb) Add description to field informationCategory and trace it to req.

Additional categories inline with SWIM Gov proposal : businessActivityType, geographicalCategorisation, intendedConsumer, lifecycleStage (with values Prospective, Operational, Retired).

category serviceType

  • this category mixes the notions Service Instance vs Service Definition with the notions about SWIM compliance (SWIM_COMPLIANT and SWIM_CANDIDATE).
  • (lightbulb) Consider separating the 2 aspects. Possibly only the first one should be kept in the Schema: serviceType with values SERVICE INSTANCE and SERVICE DEFINITION.

category applicationMessageExchangePattern

  • this is new as a category; refers correctly to req 017 (see below).
SWIM-SERV-010 Service standard reference

M

(tick)

Map: Covered , with fields title, version, description, reference, isConformant, conformantStatement within the concept of implementedStandard with code serviceStandardType = SERVICE_STANDARD (the whole being in serviceDescriptionReferences). Most fields do not map to req.

(lightbulb) Consider clarifying the usage

  • when not adhering to a service standard (an explicit statement is epexted)
  • for other cases than SERVICE_STANDARD
SWIM-SERV-011 Operational needs

M

(tick)

Map fields name and description within operationalNeed. Fields map to req, except for name.

Note: No specific fields for the IERs. these are treated as other operational needs.

SWIM-SERV-012 Service functionality

M

(tick)

Map: fields name, description, realWorldEffect within functionality. Fields map to req, except for name.

(lightbulb)Consider renaming description to function for a better alignment to req.

SWIM-SERV-013 Access and use conditions

M

(tick)

Map: fields type, name description within accessAndUseCondition. Fields map to req, except for name and type.

SWIM-SERV-014 Quality of service

M

(tick)

Map: fields name, description within qualityOfService. Fields map to req.

SWIM-SERV-015 Technical constraint

M Cond

(tick)Map: fields name, description within technicalConstraint. Fields map to req.
Service Interface Requirements

 



SWIM-SERV-016 Service interfaces

M

(tick)Map: fields name, description, interfaceProvisionSide, and endPoint.address within serviceInterface. Fields map to req.
SWIM-SERV-017 Message exchange pattern

M

(tick)

Map: field applicationMessageExchangePattern within serviceCategorisation. Field maps to req.

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

SWIM-SERV-018 TI Profile and bindings

M

(tick)

Map: fields serviceInterfaceBinding, networkInterfaceBinding, interfaceBindingDescription within serviceInterface. Fields map to req except for netwrok and interface.

To be clarified. The TI Profile and its version seem only mentioned through CodeServiceInterfaceBindingType. What about implemented standard mentioning TI Profile?

SWIM-SERV-019 Protocols and data format

M

(question)

About Data format part

  • Map: fields name, schemaLanguage, reference within exchnageSchema (within serviceInformationDescription).

About Protocol part

  • Map: field interfaceBindingDescription within serviceInterface. Field traces to req.
  • (lightbulb) Not sure this helps to satisfy the requirement.
SWIM-SERV-020 Machine-readable interface

M Cond

(tick)

Map: fields title, version, description,reference, documentType within serviceDocument (within serviceDescriptionReference) with type=MACHINE_READABLE_SERVICE_DESCRIPTION. Felds do not map to req.

SWIM-SERV-021 Service operations

M

(tick)Map: fields name, description, precondition, operationMessage, etc within operation (within Interface). Including as well message details. Fields map only partially to req.
SWIM-SERV-022 Information definition

M

(tick)

Map: fields name, description, within informationDefinition. Fields map to req. And fields title, version, description,reference, documentType within serviceDocument (within serviceDescriptionReference) with type=INFORMATION_DEFINITION. Fields do not map to req.

Note: this implies that the information definition is a separate document.

SWIM-SERV-023 AIRM conformance

M

(tick)

Map: fields airmConformant, airmVersion within informationDefinition. Fields map to req.

SWIM-SERV-024 Filter capabilities

M

(error)

TBD (no reference to req SWIM_SERV-024)

If needed the fields name and description within concepts (within serviceGeneralDescription) can be used.

SWIM-SERV-025 Service behaviour

M

(tick)

Map: fields name, description within behaviour (within serviceInterface). Fields map to req.

There is as well a document type SERVICE_BEHAVIOUR_DESCRIPTION.

SWIM-SERV-026 Model view

R

(tick)Map: fields title, version, description,reference, documentType within serviceDocument (within serviceDescriptionReference) with type=SERVICE_MODEL. Fields do not map to req.
Other Requirements

 



SWIM-SERV-027 Service validation

M

(tick)

Map: field description (and type) within validation (within serviceGeneralDescription). Field maps to req. There's as well an external document with type SERVICE_VALIDATION_REPORT.

Clarifications needed to indicate to indicate that no validation has been performed. (lightbulb)Consider extend the code CodeServiceValidationType with value NO_VALIDATION .

SWIM-SERV-028 Service monitoring

M Cond

(tick)Map: field monitoingDescription within serviceMonitoring (within servieTechnicalDescription). Reference Field maps to req.
SWIM-SERV-029 Examples of code

R

(tick)Map: fields title, version, description,reference, documentType within serviceDocument (within serviceDescriptionReference) with type=CODE_EXAMPLE. Fields do not map to req.



  • No labels

2 Comments

  1. With reference to SWIM-SERV-024, both the SWIM Manual Vol 2 and PANS-IM-SWIM explicitly mention the need for the Filter property in a Service Description.

  2. There seems to be a missing property for "Source of Information" (again, mentioned in both the SWIM Manual Vol 2 and PANS-IM-SWIM)