{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://verio.dev/schema/risk.schema.json",
  "title": "Risk analysis (ISO 14971)",
  "description": "Structure of a *.risk.yaml file: a hazard analysis where each risk carries an initial risk estimate, the control measures applied, and the residual risk after those controls.",
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "document": {
      "type": "object",
      "description": "Free-form document metadata; rendered as an editable form.",
      "additionalProperties": true
    },
    "risks": {
      "type": "object",
      "description": "Risk items keyed by identifier, e.g. RSK-STREAM-INCOMPLETE.",
      "additionalProperties": {
        "$ref": "#/$defs/risk"
      }
    }
  },
  "$defs": {
    "severity": {
      "enum": [
        "negligible",
        "minor",
        "serious",
        "critical",
        "catastrophic"
      ],
      "description": "Severity of the harm, from 1 (negligible) to 5 (catastrophic)."
    },
    "probability": {
      "enum": [
        "improbable",
        "remote",
        "occasional",
        "probable",
        "frequent"
      ],
      "description": "Probability of the harm occurring, from 1 (improbable) to 5 (frequent)."
    },
    "estimate": {
      "type": "object",
      "properties": {
        "severity": {
          "$ref": "#/$defs/severity"
        },
        "probability": {
          "$ref": "#/$defs/probability"
        }
      },
      "additionalProperties": false
    },
    "control": {
      "type": "object",
      "description": "A risk control measure. ISO 14971 requires them to be considered in priority order: inherent safety by design, then protective measures, then information for safety.",
      "properties": {
        "id": {
          "type": "string"
        },
        "type": {
          "enum": [
            "inherent_safety",
            "protective_measure",
            "information_for_safety"
          ]
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "verified_by": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Identifiers of the specification or test items that verify this control, e.g. SPC-INT02C."
        }
      },
      "required": [
        "id"
      ],
      "additionalProperties": true
    },
    "risk": {
      "type": "object",
      "properties": {
        "hazard": {
          "type": "string",
          "description": "The hazard, in the risk\u2019s own words."
        },
        "sequence_of_events": {
          "type": [
            "string",
            "null"
          ]
        },
        "hazardous_situation": {
          "type": [
            "string",
            "null"
          ]
        },
        "harm": {
          "type": [
            "string",
            "null"
          ],
          "description": "The harm \u2014 the injury or damage that can result."
        },
        "initial": {
          "$ref": "#/$defs/estimate"
        },
        "controls": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/control"
          }
        },
        "residual": {
          "$ref": "#/$defs/estimate"
        },
        "acceptability": {
          "enum": [
            "acceptable",
            "alarp",
            "unacceptable"
          ],
          "description": "Judgement on the residual risk. alarp = as low as reasonably practicable."
        }
      },
      "required": [
        "hazard"
      ],
      "additionalProperties": true
    },
    "definition": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Short label shown in the tree and in risk pickers."
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "name"
      ],
      "additionalProperties": true
    },
    "harmDefinition": {
      "allOf": [
        {
          "$ref": "#/$defs/definition"
        }
      ],
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "severity": {
          "$ref": "#/$defs/severity"
        }
      },
      "additionalProperties": true
    }
  }
}