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

Supporting material for producing JSON service descriptions

Tip
titleentry point

This is the entry point for producing JSON service descriptions.

Page JSON Service Descriptions may help understand why producing JSON service descriptions, and the constraints applicable.

Panel
borderColorlightgrey

Table of Contents

Panel
titleQuick Link

JSON example - Donlon TOBT Setting service description

JSON Guidance


The guidance helps service description authors producing JSON service descriptions.

It is divided in 2 parts that represent represent 2 valid viewpoints: starting from the requirements and starting from the schema. These 2 parts are expected to be consistent and redundant. Using one or the other should be sufficient for producing JSON service descriptions. Using both is as well a valid approach.

Guidance starting from requirements

This part of the guidance material is sub-divided according to the origin of the requirements

Each requirement is made available on a separate web page for easy referencing and linking.

Each requirement page includes on a single page all information to satisfy the requirement. That is

  • Requirement. The requirement table (with identifier, statement, rationale, etc)
  • Guidance. General guidance to satisfy the requirement, if any
  • JSON Guidance. JSON guidance to satisfy the requirement, with
    • Schema: excerpt of JSON Schema and applicable rule 
    • Guidance: Guidance for producing the relevant part(s) of a JSON service description  
    • Example: one or 2 corresponding examples in JSON

Guidance starting from the schema structure

This part of the guidance material consists of a table where each row represents an element of the schema.

Each row includes

  • name and type of the element
  • description and guidance for the element
  • rule for this element (Mandatory, Optional, etc)
  • link to the requirement(s) at the origin of this element (and so linking to the other part of the guidance)