Vulnerability: Refactor of vulnerability, fragility, damage to loss and engineering demand functions

[duncandewhurst]

In the proposed 0.3 schema, the functions part of the vulnerability component has been refactored.

Previously, most of its properties were common to all function types, and properties that were specific to a particular function type (or types) were located under vulnerability.functions.<function type>, e.g. vulnerability.functions.damage_to_loss.damage_scale_name.

In the proposed schema, everything has been moved under vulnerability.functions with a separate definition for each function type, and there is a lot of repetition between the different function types.

Here's a table comparing the properties for each function type:

property	VulnerabilityFunction	FragilityFunction	DamageToLossFunction	EngineeringDemandFunction
id	True	True	True	True
approach	True	True	True	True
relationship	True	True	True	True
hazard_primary	True	True	True	True
hazard_secondary	True	True	True	True
hazard_process_primary	True	True	True	True
hazard_process_secondary	True	True	True	True
hazard_analysis_type	True	True	True	True
intensity_measure	True	True	True	True
category	True	True	True	True
impact_type	True	True	True	True
impact_modelling	True	True	True	True
impact_metric	True	True	True	True
quantity_kind	True	True	True	True
taxonomy	True	True	True	True
analysis_details	True	True	True	True
damage_scale_name		True	True	True
damage_states_names		True	True	True
parameter				True

@matamadio I couldn't find any discussion about this refactoring - could you explain the motivation please?

On first impression, the previous approach made more sense (less repetition), but it would be good to understand what the benefits of the proposed model are.

[matamadio]

Please see #323 about the reasoning behind V redesign.
The two main reasons:

• Need to support multiple functions (turn it into array)
• Separate the socio-economic indices attributes which do not share the same kind of logic and mandatory fields of functions.

Yes there is repetition as function items share several common fields, but those instances all ref to shared definitions.

[duncandewhurst]

Happy to defer to you on the need for multiple of each function type per dataset.

Regarding repetition, I think we can reduce it further by having shared definitions for the properties shared by more than one function type. There's an illustrative example below, based on the table in the issue description.

This would make maintenance easier, but we'd likely need to create a 'composed' schema that combines/dereferences the allOfs for publication in the documentation site and use in the MDE.

Let me know what you think.

{
    "properties": {
        "vulnerability": {
            "properties": {
                "vulnerability": {
                    "items": {
                        "$ref": "#/$defs/Function"
                    }
                },
                "fragility": {
                    "items": {
                        "allOf": [
                            {"$ref": "#/$defs/Function"},
                            {"$ref": "#/$defs/Damage_scale_name"},
                            {"$ref": "#/$defs/Damage_states_names"}
                        ]
                    }
                },
                "damage_to_loss": {
                    "items": {
                        "allOf": [
                            {"$ref": "#/$defs/Function"},
                            {"$ref": "#/$defs/Damage_scale_name"},
                            {"$ref": "#/$defs/Damage_states_names"}
                        ]
                    }
                },
                "engineering_demand": {
                    "items": {
                        "allOf": [
                            {"$ref": "#/$defs/Function"},
                            {"$ref": "#/$defs/Damage_scale_name"},
                            {"$ref": "#/$defs/Damage_states_names"},
                            {"$ref": "#/$defs/Parameter"}
                        ]
                    }
                }
            }
        }
    },
    "$defs": {
        "Function": {
            "type": "object",
            "properties": {
                "id": {..},
                "approach": {..},
                "relationship": {..}
                ...
            }
        },
        "Damage_scale_name": {
            "type": "object",
            "properties": {
                "damage_scale_name": {..}
            }
        },
        ...
    }
}

[matamadio]

Sounds good! I'm positive it would still be possible to make it work in the MDE from this.

[duncandewhurst]

Great, I'll move this to "Changes needed" on the project board, for inclusion in the 1.0 release.