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

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

• Guidance starting from 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)