Working towards the next version of the SWIM Supporting Material
Supporting material for producing JSON service descriptions
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.
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
- Guidance on individual requirements - for requirements from the Service Description specification
- Guidance on non-spec requirements - for requirements from other origins
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)