Working towards the next version of the SWIM Supporting Material

Page tree

Working towards the next version of the SWIM Supporting Material

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 14 Next »

Supporting material for producing JSON service descriptions

This page sub-tree is expected to be moved to the SWIM Service Description Handbook once mature and agreed.

entry 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.

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

  • the requirement table (with identifier, statement, rationale, etc)
  • general guidance to satisfy the requirement, if any
  • 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)

A polished version of the Schema walk-through is expected to provide this part of the guidance material.

  • No labels