[Docs update] Schema reference introduction

[duncandewhurst]

What is the context or reason for the change?

Whilst working on #178, I noticed that the risk component bullets in the introductory content at the start of the schema reference are very long and are essentially lists of the fields that appear in each component. This presents a few challenges:

• Readers typically find it difficult to parse very long lists in paragraph format.
• Detail on which fields are included in each component is already repeated in the paragraphs at the start of the reference for each component and in the schema reference tables themselves.
• The list of fields in the paragraph could get out of sync with the schema.

For example, the introductory bullet for hazard is:

metadata to describe hazard data, including the main hazard type and process, triggering hazard and process, hazard intensity units, occurrence frequency of individual events, multiple hazard footprints per event, historical and stochastic events sets, and analytical methods used.

Whilst the descriptive text in the hazard section covers similar information:

The hazard component describes metadata about modeled natural hazards data, including hazard intensity footprints of historical or hypothetical events, return period hazard maps, hazard or susceptibility index, and stochastic event sets. The metadata defines the hazard type, physical process and intensity measures used in the dataset. Multiple hazards and processes (including cascading events) can be defined for each hazard, enabling users to describe dataset that contain, for example, earthquake ground shaking and liquefaction, and tsunami inundation triggered by the earthquake.

The hazard component uses hazard_type, process_type and intensity_measure consistent with the vulnerability and loss components of this standard. Spatial reference and location information are described using existing external standards. Temporal information can include date and duration of events or year of scenario, and is defined using the Dublin Core standards.

What is your proposed change?

Replace the bullets in introductory content with the higher-level descriptions of each component from the schema:

• [Hazard](): Metadata that is specific to datasets that describe processes or phenomena that may cause loss of life, injury or other health impacts, property damage, social and economic disruption or environmental degradation.
• [Exposure](): Metadata that is specific to datasets that describe the situation of people, infrastructure, housing, production capacities and other tangible human assets located in hazard-prone areas.
• [Vulnerability](): Metadata that is specific to datasets that describe the physical fragility and vulnerability relationships in relation to specific hazards or combinations of individual hazards.
• [Loss](): Metadata that is specific to datasets that describe the losses associated with people, infrastructure, housing, production capacities and other tangible human assets due to the occurrence of one or more hazards.

If you think it is helpful to include some examples of fields in the introductory content, I would pick a maximum of three for each component and actually describe the fields rather than simply naming them, e.g for hazard:

• [Hazard](): Metadata that is specific to datasets that describe processes or phenomena that may cause loss of life, injury or other health impacts, property damage, social and economic disruption or environmental degradation. For example, a classification of the type of the hazard, the units in which the intensity of the hazard is measured, and the frequency at which the hazard occurs.

[matamadio]

Agree to reduce initial bullets and avoid too much repetition.