search

GFDRR / rdl-standard

The Risk Data Library Standard (RDLS) is an open data standard to make it easier to work with disaster and climate risk data. It provides a common description of the data used and produced in risk assessments, including hazard, exposure, vulnerability, and modelled loss, or impact, data.
https://docs.riskdatalibrary.org/
Creative Commons Attribution Share Alike 4.0 International
13 stars 1 forks source link

[Docs update] hazard schema complete? #162

Closed stufraser1 closed 1 year ago

stufraser1 commented 1 year ago

The hazard schema reference section currently only contains 'event_set' which seems neither complete nor helpful for users to understand how to enter data in the hazard component.

Should this not have some emergence to hazard and process types etc?

I am working on shortening the text for each component as a 2 short para summary of the component. Propose to reserve or reuse the more detailed text on the reference page to instead describe specific examples.

odscjen commented 1 year ago

So event_sets is an array that can contain multiple event_set's. Because of this we separated out event_set into a a definition of it's own and so that's all that Hazard shows in the reference. To see the fuller details a user has to click on the link event_set which will take them to a sub-schema table and from there they can click to see the sub-schema's for event and hazard.

I agree that it's not that helpful for the user. There are 2 ways we can change this:

1) We change event_sets from an array into a single object and move the definition of event_set up into hazard rather than sitting as it's own $def. This would mean that only 1 event_set would be allowed per dataset (which is how it previously was). 2) We un-collapse the event_set in the hazard reference table. This would show ALL fields and objects that occur within hazard i.e. all the fields in event_set, hazard, event, and footprint which would make the hazard reference table very long and structured differently from the other 3 components.

duncandewhurst commented 1 year ago

Thankfully, there is a third option :-) we can uncollapse event_sets but keep its child objects and arrays collapsed to keep the length of the table manageable. That would make the schema reference table for hazard look like this:

image

Let me know if you're happy with that and I'll prepare a PR. At the same time, I'll fix the issue with the Event_set link not working, which is due to Sphinx replacing the _ character with - in HTML anchors.

stufraser1 commented 1 year ago

This would be preferable to the other options. Please go ahead

duncandewhurst commented 1 year ago

At the same time, I'll fix the issue with the Event_set link not working, which is due to Sphinx replacing the _ character with - in HTML anchors.

This requires a change to a library, I've created a PR: https://github.com/OpenDataServices/sphinxcontrib-opendataservices-jsonschema/pull/51