# Ontologies

#### Appendix C. Sample GRIx Ontologies & Schemas

This appendix provides **illustrative, non-normative** examples of the **GRIx (Global Risk & Resilience Index) ontologies and schemas** used within the Nexus Ecosystem. The purpose is to show:

* How **core concepts** of risk, resilience, and systems are represented.
* How **domain extensions** (e.g., drought–food security, coastal flood–urban infrastructure) plug into the core.
* How **chronotope** (time–space–context) and **episode** schemas structure events and decisions.

All examples are simplified; real deployments would use richer OWL/JSON-LD schemas, full SHACL/SHEx constraints, and alignment with external vocabularies.

***

### C.1 GRIx Core Ontology (Sketch)

At the highest level, GRIx defines a small set of **core entity and relationship types** for systemic risk:

* Hazard / Stressors
* Exposed units and systems
* Impacts and losses
* Interventions and decisions
* Indices and indicators

#### C.1.1 Core Entities (YAML Sketch)

```yaml
grix_core:
  version: "1.0.0"
  namespace: "https://nexus.global/grix/core#"

  entities:
    - id: "grix.HazardEvent"
      label: "Hazard Event"
      description: "Realised or simulated occurrence of a physical, biological, cyber, financial, or social hazard."
      attributes:
        - name: "hazard_type"
          type: "string"
          enum: ["drought", "flood", "heatwave", "cyclone", "pandemic", "cyber_attack", "market_shock", "civil_unrest", "multi_hazard"]
        - name: "intensity_metric"
          type: "string"
          description: "Metric used to quantify intensity (e.g., SPI, wind_speed, peak_rainfall, R0)."
        - name: "intensity_value"
          type: "float"
        - name: "return_period_years"
          type: "float"
          nullable: true
        - name: "onset_time"
          type: "datetime"
        - name: "end_time"
          type: "datetime"
        - name: "spatial_footprint"
          type: "geometry"
        - name: "source_system"
          type: "string"
          description: "Producing model or observation system (INT module)."

    - id: "grix.ExposureUnit"
      label: "Exposure Unit"
      description: "Unit that can be affected by hazards (e.g., household, asset, facility, ecosystem unit)."
      attributes:
        - name: "unit_type"
          type: "string"
          enum: ["household", "farm", "substation", "hospital", "school", "bridge", "company", "ecosystem_patch"]
        - name: "location"
          type: "geometry"
        - name: "admin_unit_id"
          type: "string"
        - name: "population"
          type: "integer"
          nullable: true
        - name: "economic_value_usd"
          type: "float"
          nullable: true
        - name: "vulnerability_class"
          type: "string"
          nullable: true

    - id: "grix.SystemNode"
      label: "System Node"
      description: "Node within an infrastructure, economic, or social network (e.g., grid node, hospital, trading hub)."
      attributes:
        - name: "system_type"
          type: "string"
          enum: ["power_grid", "transport_network", "health_system", "water_network", "financial_system", "supply_chain"]
        - name: "node_role"
          type: "string"
          enum: ["source", "hub", "sink", "bridge", "redundant"]
        - name: "capacity"
          type: "float"
          nullable: true
        - name: "criticality_score"
          type: "float"
          range: [0.0, 1.0]

    - id: "grix.ImpactRecord"
      label: "Impact Record"
      description: "Observed or modelled impact on exposure units and systems due to one or more hazard events."
      attributes:
        - name: "impact_type"
          type: "string"
          enum: ["mortality", "morbidity", "economic_loss", "service_disruption", "displacement", "ecological_damage"]
        - name: "value"
          type: "float"
        - name: "unit"
          type: "string"
        - name: "reference_period"
          type: "string"
          description: "Time window of impact measurement, e.g., 'event', 'year', 'season'."

    - id: "grix.Index"
      label: "Index"
      description: "Composite indicator summarising risk, resilience, stress, or equity."
      attributes:
        - name: "index_id"
          type: "string"
        - name: "index_type"
          type: "string"
          enum: ["risk", "resilience", "systemic_stress", "equity", "exposure"]
        - name: "value"
          type: "float"
        - name: "scale"
          type: "string"
          enum: ["local", "subnational", "national", "regional", "global", "portfolio"]
        - name: "calculation_time"
          type: "datetime"
        - name: "method_ref"
          type: "string"
          description: "Reference to method/model card used."

    - id: "grix.Decision"
      label: "Decision"
      description: "Formal decision that materially responds to risk evidence (e.g., facility trigger, budget reallocation, regulatory change)."
      attributes:
        - name: "decision_id"
          type: "string"
        - name: "decision_type"
          type: "string"
          enum: ["capital_trigger", "budget_allocation", "policy_change", "operational_action"]
        - name: "deciding_body"
          type: "string"
        - name: "decision_time"
          type: "datetime"
        - name: "jurisdiction"
          type: "string"
        - name: "nr m_profile_id"
          type: "string"
          description: "NRM Profile under which decision is framed."
```

#### C.1.2 Core Relationships

```yaml
grix_core.relationships:
  - id: "grix.HazardImpactsExposure"
    from: "grix.HazardEvent"
    to: "grix.ExposureUnit"
    label: "impacts"
    attributes:
      - name: "mechanism"
        type: "string"
        description: "Pathway of impact (e.g., inundation, heat_stress, supply_chain_disruption)."

  - id: "grix.ExposureLocatedInSystemNode"
    from: "grix.ExposureUnit"
    to: "grix.SystemNode"
    label: "served_by"

  - id: "grix.ImpactAtExposure"
    from: "grix.ImpactRecord"
    to: "grix.ExposureUnit"
    label: "impact_on"

  - id: "grix.ImpactAttributedToHazard"
    from: "grix.ImpactRecord"
    to: "grix.HazardEvent"
    label: "caused_by"

  - id: "grix.IndexComputedForScope"
    from: "grix.Index"
    to: "grix.ChronotopeScope"
    label: "computed_for"

  - id: "grix.DecisionSupportedByAEP"
    from: "grix.Decision"
    to: "grix.AEP"
    label: "supported_by"

  - id: "grix.DecisionImplementsPlaybookStep"
    from: "grix.Decision"
    to: "grix.PlaybookStep"
    label: "implements"
```

***

### C.2 Domain Extension 1: Drought & Food Security (GRIx–Drought–Food)

This extension is consistent with the **East Africa Drought & Food Security Rail** in Appendix B.

#### C.2.1 Entities

```yaml
grix_drought_food:
  version: "1.0.0"
  namespace: "https://nexus.global/grix/drought-food#"

  entities:
    - id: "df.DroughtEvent"
      extends: "grix.HazardEvent"
      attributes:
        - name: "spi_value"
          type: "float"
          description: "Standardised Precipitation Index value."
        - name: "season"
          type: "string"
          enum: ["long_rains", "short_rains", "main_rains", "dry_season"]
        - name: "crop_calendar_phase"
          type: "string"
          enum: ["planting", "vegetative", "flowering", "harvest"]

    - id: "df.PastureUnit"
      extends: "grix.ExposureUnit"
      attributes:
        - name: "dominant_vegetation_type"
          type: "string"
        - name: "stocking_density"
          type: "float"
          unit: "livestock_units_per_ha"

    - id: "df.HouseholdLivelihoodUnit"
      extends: "grix.ExposureUnit"
      attributes:
        - name: "livelihood_zone"
          type: "string"
        - name: "income_sources"
          type: "string[]"
        - name: "poverty_quintile"
          type: "integer"
          range: [1, 5]
        - name: "female_headed"
          type: "boolean"
        - name: "pastoralist"
          type: "boolean"

    - id: "df.DroughtImpactRecord"
      extends: "grix.ImpactRecord"
      attributes:
        - name: "food_consumption_score"
          type: "float"
        - name: "coping_strategy_index"
          type: "float"
        - name: "livestock_mortality_rate"
          type: "float"
        - name: "yield_loss_pct"
          type: "float"

    - id: "df.FoodSecurityIndex"
      extends: "grix.Index"
      attributes:
        - name: "dimension"
          type: "string"
          enum: ["availability", "access", "utilisation", "stability"]
        - name: "uncertainty_band_lower"
          type: "float"
        - name: "uncertainty_band_upper"
          type: "float"
```

#### C.2.2 Relationships

```yaml
grix_drought_food.relationships:
  - id: "df.DroughtAffectsPasture"
    from: "df.DroughtEvent"
    to: "df.PastureUnit"
    label: "affects_pasture"
    attributes:
      - name: "ndvi_anomaly"
        type: "float"
      - name: "grazing_days_lost"
        type: "float"

  - id: "df.DroughtAffectsHouseholdLivelihood"
    from: "df.DroughtEvent"
    to: "df.HouseholdLivelihoodUnit"
    label: "affects_livelihood"
    attributes:
      - name: "income_loss_pct"
        type: "float"
      - name: "probability_distress_migration"
        type: "float"

  - id: "df.FoodSecurityIndexAtAdminUnit"
    from: "df.FoodSecurityIndex"
    to: "grix.ChronotopeScope"
    label: "computed_for"
    attributes:
      - name: "admin_level"
        type: "integer"
      - name: "aggregation_method"
        type: "string"
        enum: ["population_weighted_mean", "poor_household_weighted"]
```

***

### C.3 Domain Extension 2: Coastal Flood & Urban Infrastructure (GRIx–Coastal–Urban)

Aligned with the **Coastal Flood & Urban Infrastructure NRM Pack** in Appendix B.

#### C.3.1 Entities

```yaml
grix_coastal_urban:
  version: "1.0.0"
  namespace: "https://nexus.global/grix/coastal-urban#"

  entities:
    - id: "cu.CoastalFloodEvent"
      extends: "grix.HazardEvent"
      attributes:
        - name: "return_period_category"
          type: "string"
          enum: ["rp10", "rp50", "rp100", "rp200"]
        - name: "sea_level_anomaly_m"
          type: "float"
        - name: "storm_surge_height_m"
          type: "float"

    - id: "cu.CoastalSegment"
      extends: "grix.ExposureUnit"
      attributes:
        - name: "mean_sea_level_m"
          type: "float"
        - name: "defence_standard"
          type: "string"
          enum: ["none", "1-in-10", "1-in-50", "1-in-100", "1-in-200"]
        - name: "wetland_buffer_presence"
          type: "boolean"

    - id: "cu.CriticalInfrastructureNode"
      extends: "grix.SystemNode"
      attributes:
        - name: "infra_type"
          type: "string"
          enum: ["substation", "hospital", "water_plant", "port_terminal", "bridge"]
        - name: "elevation_masl"
          type: "float"
        - name: "redundancy_level"
          type: "integer"
          range: [0, 3]

    - id: "cu.UrbanBlock"
      extends: "grix.ExposureUnit"
      attributes:
        - name: "population"
          type: "integer"
        - name: "housing_quality_index"
          type: "float"
          range: [0.0, 1.0]

    - id: "cu.ServiceDisruptionIndex"
      extends: "grix.Index"
      attributes:
        - name: "sector"
          type: "string"
          enum: ["electricity", "water", "healthcare", "transport"]
        - name: "service_disruption_score"
          type: "float"
          range: [0.0, 1.0]
```

#### C.3.2 Relationships

```yaml
grix_coastal_urban.relationships:
  - id: "cu.SegmentProtectsNode"
    from: "cu.CoastalSegment"
    to: "cu.CriticalInfrastructureNode"
    label: "protects"
    attributes:
      - name: "protection_effectiveness"
        type: "float"
        range: [0.0, 1.0]

  - id: "cu.NodeServesBlock"
    from: "cu.CriticalInfrastructureNode"
    to: "cu.UrbanBlock"
    label: "serves"
    attributes:
      - name: "service_type"
        type: "string"

  - id: "cu.FloodImpactsInfraNode"
    from: "cu.CoastalFloodEvent"
    to: "cu.CriticalInfrastructureNode"
    label: "inundates"
    attributes:
      - name: "inundation_depth_m"
        type: "float"
      - name: "expected_outage_hours"
        type: "float"
```

***

### C.4 Chronotope Schema (Time–Space–Context Model)

Chronotope schemas encode how **indices, AEPs, and decisions** are anchored in time, space, and institutional context.

```yaml
chronotope_schema:
  version: "1.0.0"
  namespace: "https://nexus.global/grix/chronotope#"

  entity: "grix.ChronotopeScope"
  description: "Canonical representation of the spatio-temporal and institutional scope of an NRM artefact."

  attributes:
    - name: "scope_id"
      type: "string"
    - name: "time_window_start"
      type: "datetime"
    - name: "time_window_end"
      type: "datetime"
    - name: "time_resolution"
      type: "string"
      enum: ["event", "hourly", "daily", "weekly", "monthly", "seasonal", "annual", "multi_year"]
    - name: "spatial_reference_type"
      type: "string"
      enum: ["point", "grid", "admin_unit", "basin", "network_segment", "portfolio"]
    - name: "spatial_reference_id"
      type: "string"
      description: "Identifier (e.g., admin code, basin id, grid id, network id)."
    - name: "institutional_scope"
      type: "string[]"
      description: "Institutions / programmes covered (e.g., ministries, utilities, facilities)."
    - name: "population_focus"
      type: "string"
      nullable: true
      description: "Target population (e.g., 'national', 'pastoralists', 'low-income urban')."
```

***

### C.5 Episode Schema (Signals → Decisions → Actions → Outcomes)

Episodes are the main **unit of learning** in the Chronotope & Episodic Memory Fabric.

```yaml
episode_schema:
  version: "1.0.0"
  namespace: "https://nexus.global/grix/episode#"

  entity: "grix.Episode"
  description: "Structured representation of a risk episode from signals to outcomes."

  attributes:
    - name: "episode_id"
      type: "string"
    - name: "episode_type"
      type: "string"
      enum: ["shock", "near_miss", "exercise", "policy_change"]
    - name: "chronotope_scope_id"
      type: "string"
    - name: "triggering_signals"
      type: "string[]"
      description: "IDs of indices, alerts, or observational thresholds crossed."
    - name: "aep_ids"
      type: "string[]"
      description: "IDs of AEPs that informed the episode."
    - name: "decisions_ids"
      type: "string[]"
      description: "Decisions taken as part of the episode."
    - name: "actions_ids"
      type: "string[]"
      description: "Operational or policy actions executed."
    - name: "outcome_metrics"
      type: "map<string,float>"
      description: "Key performance and equity indicators (e.g., people assisted, days of outage avoided)."
    - name: "equity_distribution_metrics"
      type: "map<string,float>"
      description: "Coverage and distribution across groups (e.g., by income, gender, region)."
    - name: "lessons_learned_refs"
      type: "string[]"
      description: "References to post-mortems, evaluations, and recommendations."

  relationships:
    - id: "episode_has_hazard_event"
      from: "grix.Episode"
      to: "grix.HazardEvent"
      label: "includes_hazard"

    - id: "episode_has_decision"
      from: "grix.Episode"
      to: "grix.Decision"
      label: "includes_decision"

    - id: "episode_has_impact"
      from: "grix.Episode"
      to: "grix.ImpactRecord"
      label: "includes_impact"
```

***

### C.6 AEP Structural Schema (High-Level)

Finally, a **simplified skeleton** of an AEP schema showing how GRIx ontologies are used inside a pack of evidence.

```yaml
aep_schema:
  version: "1.0.0"
  namespace: "https://nexus.global/aep#"

  entity: "grix.AEP"
  description: "Assurance & Evidence Pack used for NRM decisions."

  attributes:
    - name: "aep_id"
      type: "string"
    - name: "title"
      type: "string"
    - name: "nrm_profile_id"
      type: "string"
    - name: "eql_level"
      type: "string"
      enum: ["EQL1", "EQL2", "EQL3", "EQL4", "EQL5"]
    - name: "cl_target"
      type: "string"
      enum: ["CL1", "CL2", "CL3", "CL4"]
    - name: "chronotope_scope_id"
      type: "string"
    - name: "int_modules_used"
      type: "string[]"
      description: "OSINT/INT families used (CLIMATEINT, CYBINT, etc.)."
    - name: "data_sources"
      type: "list"
      items:
        - name: "source_id"
          type: "string"
        - name: "sdz_class"
          type: "string"
        - name: "licence"
          type: "string"
    - name: "models_used"
      type: "list"
      items:
        - name: "model_id"
          type: "string"
        - name: "version"
          type: "string"
        - name: "model_card_ref"
          type: "string"
    - name: "indices_produced"
      type: "string[]"
      description: "GRIx index identifiers included in this AEP."
    - name: "uncertainty_characterisation"
      type: "string"
      description: "Narrative + structured summary of uncertainty and limitations."
    - name: "co_authorship"
      type: "list"
      items:
        - name: "actor_type"
          type: "string"
          enum: ["NCC", "RNC", "agency", "community", "indigenous", "vendor"]
        - name: "actor_id"
          type: "string"
        - name: "role"
          type: "string"
    - name: "grf_assurance_status"
      type: "string"
      enum: ["self_declared", "peer_reviewed", "grf_certified"]
    - name: "issued_at"
      type: "datetime"
    - name: "valid_until"
      type: "datetime"
      nullable: true
```

***

These sample ontologies and schemas demonstrate how **GRIx** provides a **unified semantic fabric** across hazards, sectors, and scales, and how **domain packs** extend that fabric without breaking interoperability. In the full whitepaper, these examples can be expanded into:

* Machine-readable OWL/Turtle and JSON-LD artefacts.
* SHACL/SHEx shapes for validation.
* Mapping tables to external vocabularies (e.g., INSPIRE, HL7, ISO TC211, OGC).

so that implementers can move directly from conceptual design to concrete, verifiable implementations on the Nexus Rail.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.therisk.global/organization/standardization/nexus-rail/nexus-based-risk-management-nrm/technology/appendices/ontologies.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.