Update diagrams, top-level schema description and schema reference

[duncandewhurst]

Related issues

• Closes [Docs update] Update or remove mermaid flowcharts #178

Description

In addition to updating the diagrams per #178, this PR also:

• Updates the top-level description in the schema to align with the diagram in docs/rdl/what.md
• Adds the schema descriptions for dataset, resource and each hazard component to docs/reference/schema.md

You can preview the changes here: https://rdl-standard.readthedocs.io/en/178-diagrams/reference/schema/

Merge checklist

• Update the changelog (style guide)
• Run ./manage.py pre-commit

If you added or removed a field:

• Update the collapse option of the jsonschema directives for dataset, resource, hazard, exposure, vulnerability and loss on reference/schema.md

Having trouble?

See how to resolve check failures.

[duncandewhurst]

Noting that the exposure diagram may need to be updated if there are further changes in #204

[duncandewhurst]

Based on @matamadio's feedback in yesterday's call, I've removed empty objects and arrays from the diagrams and added an explanatory sentence to describe how arrays are represented.

Here's how the changes look to the hazard diagram (since it is the most complex):

Before

After

I considered adding an extra object to each array, but I think it makes the diagram too complicated:

[matamadio]

Thanks, they read better now.
Just one perplexity on the word "subset". While formally correct, it can induce to think this is a small part of the whole hazard schema; rather, hazard attributes are a subset of the whole schema. But to be aligned with the rest of the docs, I would use "component" instead. Then for each diagram paragraph I would rephrase as:

The following diagram shows the key attributes of the [hazard] component, with required fields highlighted in blue.

[duncandewhurst]

Since @matamadio has approved, I'm going to bypass branch protections and merge this PR so that these changes are available on dev before the workshop today. (Merging was blocked because @stufraser1's earlier review was marked as requesting changes, all of which have been addressed).