Why JSON service descriptions

The European SWIM Registry has developed a JSON Schema for the import/export of service descriptions. 

That JSON Schema is a practical answer to the need for a template / schema as expressed by stakeholders in support of the production of service descriptions.

Such a schema 

• benefits service providers in facilitating the production of service descriptions, including importing in registry and conformance to the SW specifications
• benefits service consumers with enhanced harmonisation of service descriptions 
• allows service descriptions to be processed by systems this includes upload into a system, exchange between systems, and transformation (eg to service overview).

Constraints on JSON service descriptions

The JSON service descriptions are constrained by

• requirements. The service description spec requirements, but also some additional requirements (see below)
• the JSON schema (see Service Metadata Schema) 
• validation rules (within the Registry application)

Schema

Documentation within the schema

Each schema element is documented with a "documentation" annotation.

This "documentation" annotation includes

• a small description for the element
• a trace to the requirement(s) justifying the presence of this element

Validation rules

Service description requirements 

The following sources for service descriptions requirements have been identified:

• the Service Description specification, 
• the ICAO Service Overview requirements, 
• the Registry requirements.

Service Description specification 

• Source = EUROCONTROL specifications for SWIM Service Description
• Rationale = 

• See SWIM Service Description Handbook and in particular Guidance on individual requirements

   SD spec requirements [+]

  Requirement (link)	Identifier	Title	Level of Implementation
  General Requirements		General Requirements
  SWIM-SERV-001 Description coverage	SWIM-SERV-001	Service description coverage	Mandatory
  SWIM-SERV-002 Description language	SWIM-SERV-002	Service description language	Mandatory
  SWIM-SERV-003 Define abbreviations	SWIM-SERV-003	Define abbreviations and acronyms	Mandatory
  SWIM-SERV-004 Use standard abbreviations	SWIM-SERV-004	Use standard abbreviations and acronyms	Recommended
  SWIM-SERV-005 Description identification	SWIM-SERV-005	Service description identification	Mandatory
  SWIM-SERV-006 Service identification	SWIM-SERV-006	Service identification	Mandatory
  SWIM-SERV-007 Service abstract	SWIM-SERV-007	Service abstract	Mandatory
  SWIM-SERV-008 Service provider	SWIM-SERV-008	Service provider	Mandatory
  SWIM-SERV-009 Service categories	SWIM-SERV-009	Service categories	Mandatory
  SWIM-SERV-010 Service standard reference	SWIM-SERV-010	Service standard reference	Mandatory
  SWIM-SERV-011 Operational needs	SWIM-SERV-011	Operational needs	Mandatory
  SWIM-SERV-012 Service functionality	SWIM-SERV-012	Service functionality	Mandatory
  SWIM-SERV-013 Access and use conditions	SWIM-SERV-013	Service access and use conditions	Mandatory
  SWIM-SERV-014 Quality of service	SWIM-SERV-014	Quality of service	Mandatory
  SWIM-SERV-015 Technical constraint	SWIM-SERV-015	Technical constraint	Mandatory Conditional
  Service Interface Requirements		Service Interface Requirements
  SWIM-SERV-016 Service interfaces	SWIM-SERV-016	Service interfaces	Mandatory
  SWIM-SERV-017 Message exchange pattern	SWIM-SERV-017	Message exchange pattern	Mandatory
  SWIM-SERV-018 TI Profile and bindings	SWIM-SERV-018	SWIM TI Profile and interface bindings	Mandatory
  SWIM-SERV-019 Protocols and data format	SWIM-SERV-019	Service interface protocols and data format	Mandatory
  SWIM-SERV-020 Machine-readable interface	SWIM-SERV-020	Machine-readable service interface definition	Mandatory Conditional
  SWIM-SERV-021 Service operations	SWIM-SERV-021	Service operations	Mandatory
  SWIM-SERV-022 Information definition	SWIM-SERV-022	Information definition	Mandatory
  SWIM-SERV-023 AIRM conformance	SWIM-SERV-023	AIRM conformance	Mandatory
  SWIM-SERV-024 Filter capabilities	SWIM-SERV-024	Filter capabilities	Mandatory
  SWIM-SERV-025 Service behaviour	SWIM-SERV-025	Service behaviour	Mandatory
  SWIM-SERV-026 Model view	SWIM-SERV-026	Model view	Recommended
  Other Requirements		Other Requirements
  SWIM-SERV-027 Service validation	SWIM-SERV-027	Service validation	Mandatory
  SWIM-SERV-028 Service monitoring	SWIM-SERV-028	Service monitoring	Mandatory Conditional
  SWIM-SERV-029 Examples of code	SWIM-SERV-029	Examples of code	Recommended
  Not a requirement		Not a requirement
  SWIM-SERV-ADD Additional info	SWIM-SERV-ADD	Additional optional information	Optional

ICAO Service Overview 

• Source = the draft ICAO Service Overview (see Service Overview from "Get into SWIM" session for a summary)
• Rationale = by satisfying these additional requirements, a service description contains all elements to produce a service overview. The intention is that service description authors would write a single document the burden to produce to write a single document 

SWIM EUR Registry 

• Source = The SWIM EUR Registry User Requirements Document (URD)
• Rationale = by satisfying these additional requirements, a service description can be imported in the SWIM EUR Registry and become discoverable.