# YAML

#### Appendix B. Example `rail.yaml` and `pack.yaml` Files

This appendix provides **illustrative, non-normative** examples of the Nexus configuration DSLs:

* `rail.yaml` — configuration for a **Nexus Rail (NXSR)**
* `pack.yaml` — configuration for a **Nexus Pack (NXPCK)**

They are intended to show **shape, structure, and semantics**, not to prescribe exact fields or values. Real deployments would refine, extend, and localise these templates.

***

### B.1 Example `rail.yaml` — “East Africa Drought & Food Security Rail”

This example describes a **regional, multi-hazard Nexus Rail** focused on **drought and food security** across East Africa, operated by the **Kenya Nexus RNC** in collaboration with regional partners.

```yaml
api_version: nxrail.v1
kind: NexusRail

metadata:
  rail_id: "nxsr.eaf.drought-food.v1"
  display_name: "East Africa Drought & Food Security Rail"
  description: >
    Regional Nexus Rail supporting anticipatory action, disaster risk finance,
    and fiscal risk management for drought and food security in East Africa.
    Operated by Kenya Nexus RNC with participating Member States, DFIs,
    agricultural and humanitarian partners.
  owners:
    rnc_operator: "Kenya Nexus RNC"
    sovereign_sponsors:
      - "Ministry of Finance, Kenya"
      - "Ministry of Agriculture, Ethiopia"
      - "Ministry of Agriculture, Somalia"
    grf_steward: "GRF Regional Committee for East Africa"
    gcri_steward: "GCRI / East Africa Risk & Resilience Lab"
  labels:
    region: "East Africa"
    mission: "drought-food-security"
    status: "production"
    trl: 8

scope:
  geography:
    iso_countries:
      - "KE"
      - "ET"
      - "SO"
      - "UG"
      - "TZ"
    basins:
      - "HornOfAfrica_Drylands"
  thematic:
    primary:
      - "drought"
      - "food_security"
      - "agricultural_livelihoods"
    secondary:
      - "macro_fiscal_risk"
      - "humanitarian_response"
  institutional_perimeter:
    ministries:
      - "Finance"
      - "Agriculture"
      - "Water & Irrigation"
      - "Social Protection"
    agencies:
      - "National Drought Management Authorities"
      - "National Meteorological Services"
      - "National Statistics Offices"
    financial_institutions:
      - "Central Banks (participating)"
      - "Regional Development Bank"
      - "Local commercial banks & MFIs (selected)"
    humanitarian_actors:
      - "WFP (regional)"
      - "FAO (regional)"
      - "Key NGOs and local CSOs"
    community_representatives:
      - "Pastoralist associations"
      - "Women’s farmer cooperatives"
      - "Indigenous councils"

governance:
  grf_ip_profiles:
    - "grfip.drr.eaf.v1"
    - "grfip.drf.sovereign.v1"
  cl_minimums:
    rail_overall: "CL3"
    observatories: "CL3"
    capital_linked_programmes: "CL3"
  eql_minimums:
    early_warning_use: "EQL2"
    planning_and_budget_use: "EQL3"
    capital_triggers: "EQL4"
  nvm_profiles:
    default_quorum: "nvm.3of6.gov-fin-infra-acad-civil-indig.v1"
    high_stakes_quorum: "nvm.4of6.gov-fin-infra-community.v1"
  governance_bodies:
    rail_dao_id: "dao.eaf.drought-food"
    nvm_committee_id: "nvmc.eaf.drought-food"
    community_council_id: "cc.eaf.drought-food"
  decision_classes:
    - name: "config_change_low"
      description: "Technical parameter tuning, non-capital-critical"
      quorum_profile: "default_quorum"
    - name: "config_change_high"
      description: "Changes to CL/EQL minima, pack activation for capital programmes"
      quorum_profile: "high_stakes_quorum"
    - name: "capital_facility_approval"
      description: "Approval of NRM-linked DRF facilities"
      quorum_profile: "high_stakes_quorum"

sdz_config:
  sdz_classes:
    - id: "sdz.sov.national"
      description: "National sovereign data zone, in-country processing only"
    - id: "sdz.reg.regional"
      description: "Regional aggregation zone under EAC/IGAD data agreements"
    - id: "sdz.sens.indigenous"
      description: "Indigenous and community-controlled data with opaque knowledge rules"
  sdz_assignments:
    drought_indicators:
      default_sdz: "sdz.sov.national"
      allowed_cross_border_aggregations:
        - "sdz.reg.regional"
    household_survey_data:
      default_sdz: "sdz.sov.national"
      restrictions:
        pii_handling: "compute_to_data_only"
        anonymisation_required: true
    indigenous_knowledge_records:
      default_sdz: "sdz.sens.indigenous"
      opaque_knowledge: true
      consent_regime: "conditional_collective_consent"
  lawful_basis_matrix_ref: "lbm.eaf.drought-food.v1"

technical_topology:
  hosting:
    primary_region: "africa-south1"
    secondary_region: "europe-west1"
    platform_profile: "nxref.fabric.onelake.v1"
  nxstudio_clusters:
    - id: "nxstudio.eaf.drought-food.primary"
      location: "africa-south1"
      sdz_supported:
        - "sdz.sov.national"
        - "sdz.reg.regional"
  observatories:
    - id: "nxobs.eaf.climate-drought"
      type: "climate-hydro-agro"
      host_institution: "GCRI / East Africa Lab"
      cl_level: "CL3"
      eql_capability: "EQL4"
    - id: "nxobs.eaf.macro-food"
      type: "macro-fiscal-food"
      host_institution: "Regional Development Bank"
      cl_level: "CL2"
      eql_capability: "EQL3"
  connectivity:
    nxn_slices:
      - id: "nxn.eaf.sovereign"
        qos: "high"
        use_cases:
          - "early_warning"
          - "nxobs_data_ingest"
      - id: "nxn.eaf.humanitarian"
        qos: "medium"
        use_cases:
          - "field_reporting"
          - "community_dashboards"

packs:
  activated_packs:
    - pack_id: "nxpck.drought-food.eaf.v2"
      version: "2.1.0"
      profiles_enabled:
        - "nrm.drought.food.household"
        - "nrm.drought.food.sovereign_fiscal"
      capital_linked:
        - facility_id: "drf.eaf.drought.window1"
          eql_min: "EQL4"
          cl_min: "CL3"
          triggers:
            index_id: "idx.eaf.drought_veg_index.v3"
            threshold_spec: "p95_shortfall"
    - pack_id: "nxpck.health-nutrition.eaf.v1"
      version: "1.0.2"
      profiles_enabled:
        - "nrm.nutrition.household"
      capital_linked: []

slo:
  timeliness:
    - name: "early_warning_bulletin"
      description: "Seasonal drought bulletin from event detection to public release"
      target_hours: 72
      percentile: "P90"
    - name: "capital_trigger_median"
      description: "Median time from trigger condition met to facility disbursement"
      target_days: 21
      percentile: "P50"
  availability:
    - name: "nxobs_core_services"
      target_uptime_pct: 99.5
      window_days: 30
  quality:
    - name: "aep_eql_uplift"
      description: "Share of AEPs for fiscal decisions at EQL≥3"
      target_pct: 90
  coverage:
    - name: "food_insecure_population_coverage"
      description: "Share of severely food-insecure population covered by NRM-informed programmes"
      target_pct: 80

safety_envelopes:
  ai_automation:
    max_safety_tier_without_hil: "tier2"
    prohibited_actions:
      - "direct_cash_disbursement_without_human_approval"
      - "automated_programme_shutdown"
    required_hil_decision_classes:
      - "capital_facility_approval"
      - "emergency_mode_activation"
  model_usage:
    prohibited_domains:
      - model_id: "mdl.generic_crop_model.v1"
        outside_geographies:
          - "!HornOfAfrica_Drylands"
  data_combination:
    high_risk_pairs:
      - left: "household_survey_data"
        right: "individual_health_records"
        allowed: false

dr_bc:
  modes:
    - name: "degraded_connectivity_mode"
      description: "Operation with intermittent connectivity to regional hub"
      nxmirror_enabled: true
      aep_eql_ceiling: "EQL3"
      autonomous_actions_restricted: true
    - name: "crisis_mode"
      description: "Declared regional drought emergency"
      modified_slo:
        timeliness:
          - name: "capital_trigger_median"
            target_days: 14
      enhanced_governance:
        quorum_profile: "high_stakes_quorum"
        additional_observers:
          - "Independent Humanitarian Panel"
  resync_policy:
    max_staleness_hours: 24
    conflict_resolution: "chronotope_consistent_merge_with_nvm_review"

meta:
  created_at: "2026-03-15T10:00:00Z"
  created_by: "GCRI/EAF-Rail-Design-Team"
  last_updated_at: "2027-01-08T09:30:00Z"
  last_updated_by: "RailDAO.eaf.drought-food"
  change_control_process: "nep.nxrail.eaf.v1"
  documentation_urls:
    - "https://example.org/docs/nxsr/eaf-drought-food/v2.1"
```

***

### B.2 Example `pack.yaml` — “Coastal Flood & Urban Infrastructure NRM Pack”

This example describes a **Nexus Pack** for **coastal flood and urban infrastructure risk**, designed to be deployable on multiple rails (e.g., EU coastal cities, Small Island Developing States).

```yaml
api_version: nxpack.v1
kind: NexusPack

metadata:
  pack_id: "nxpck.coastal-flood-urban.v1"
  display_name: "Coastal Flood & Urban Infrastructure NRM Pack"
  description: >
    Domain pack for analysing coastal flood risk and impacts on urban
    infrastructure systems, supporting early warning, contingency planning,
    and NRM-linked risk finance for ports, transport, power, and housing.
  domains:
    - "climate"
    - "infrastructure"
    - "urban"
    - "sovereign_fiscal"
  status: "production"
  owners:
    primary_steward: "GCRI / Coastal & Urban Systems Lab"
    grf_profile: "grfip.climate.infra.v1"
    g ra_liaison: "GRA / Resilience Finance Working Group"
  labels:
    hazard: "coastal_flood"
    infra: "urban"
    trl: 8

compatibility:
  nxss_version_min: "1.3.0"
  nxss_version_max: "2.0.0"
  required_int_modules:
    - "CLIMATEINT"
    - "GEOINT"
    - "INFRAINT"
    - "MACROINT"
  supported_profiles:
    - "nrm.flood.urban.infrastructure"
    - "nrm.flood.urban.sovereign_fiscal"
  cl_eql_targets:
    planning_use:
      target_cl: "CL2"
      target_eql: "EQL3"
    capital_triggers:
      target_cl: "CL3"
      target_eql: "EQL4"

dependencies:
  packs:
    - "nxpck.generic-climate-hazard.v1"
    - "nxpck.macro-fiscal.v1"
  external_schemas:
    - "https://example.org/schemas/infrastructure/urban-grid-topology.v2.json"
    - "https://example.org/schemas/building-vulnerability.curves.v1.json"

grix_extensions:
  entities:
    - id: "coastal_segment"
      extends: "grix.geo.segment"
      attributes:
        - name: "mean_sea_level"
          type: "float"
          unit: "m"
        - name: "storm_surge_height"
          type: "float"
          unit: "m"
        - name: "defence_standard"
          type: "string"
          enum: ["none", "1-in-10", "1-in-50", "1-in-100", "1-in-200"]
    - id: "critical_infrastructure_node"
      extends: "grix.infra.node"
      attributes:
        - name: "infra_type"
          type: "string"
          enum: ["substation", "hospital", "water_plant", "port_terminal", "bridge"]
        - name: "redundancy_level"
          type: "integer"
          range: [0, 3]
        - name: "elevation_masl"
          type: "float"
    - id: "urban_block"
      extends: "grix.geo.gridcell"
      attributes:
        - name: "population"
          type: "integer"
        - name: "housing_quality_index"
          type: "float"
          range: [0.0, 1.0]
  relationships:
    - id: "coastal_segment_protects_node"
      from: "coastal_segment"
      to: "critical_infrastructure_node"
      cardinality: "1..N"
    - id: "node_serves_block"
      from: "critical_infrastructure_node"
      to: "urban_block"
      cardinality: "1..N"
  indices:
    - id: "idx.coastal_flood_exposure.v1"
      description: "Expected inundation depth and exposed infrastructure by return period"
      inputs:
        - "CLIMATEINT.sea_level"
        - "CLIMATEINT.storm_surge"
        - "GEOINT.elevation"
        - "INFRAINT.critical_infrastructure_node"
      outputs:
        - "expected_inundation_depth"
        - "exposed_critical_nodes"
      aggregation_scales:
        - "urban_area"
        - "administrative_unit"
        - "national"
    - id: "idx.urban_service_disruption.v1"
      description: "Composite index of expected disruption to essential services"
      inputs:
        - "idx.coastal_flood_exposure.v1"
        - "INFRAINT.network_topology"
        - "urban_block.population"
      outputs:
        - "service_disruption_score"
      aggregation_scales:
        - "urban_area"
        - "national"
        - "portfolio"

data_sources:
  reference_datasets:
    - id: "ds.global_elevation_coastal.v1"
      provider: "GCRI / EO & Topography Team"
      sdz_default: "sdz.reg.regional"
    - id: "ds.national_building_footprints.v1"
      provider: "National Mapping Agencies"
      sdz_default: "sdz.sov.national"
      pii: false
    - id: "ds.critical_infrastructure_registry.v1"
      provider: "National Infrastructure Agencies"
      sdz_default: "sdz.sov.national"
      sensitivity: "high"
  pipelines:
    - id: "pl.coastal_flood_hazard.v1"
      type: "etl"
      description: "Ingest and harmonise storm surge, sea-level rise, and bathymetry data"
      inputs:
        - "CLIMATEINT.sea_level_timeseries"
        - "CLIMATEINT.storm_surge_scenarios"
        - "GEOINT.bathymetry"
      outputs:
        - "hazard_surface_rp10"
        - "hazard_surface_rp100"
    - id: "pl.infra_exposure.v1"
      type: "etl"
      description: "Link hazard surfaces to critical infrastructure and urban blocks"
      inputs:
        - "hazard_surface_rp*"
        - "INFRAINT.critical_infrastructure_node"
        - "urban_block"
      outputs:
        - "node_inundation_depth"
        - "block_inundation_stats"

models:
  - id: "mdl.coastal_inundation.v1"
    type: "physics_based"
    description: "Coastal inundation model combining storm surge and sea-level projections"
    owner: "GCRI / Coastal Systems"
    training_data:
      provenance: "peer_reviewed_published"
      region_coverage: "global_coastal"
    performance:
      calibration_score: 0.92
      limitations:
        - "Reduced accuracy in estuaries with complex bathymetry"
    intended_use:
      - "scenario_analysis"
      - "planning"
  - id: "mdl.service_disruption.v1"
    type: "network_impact"
    description: "Network-based model of service disruption due to coastal flooding"
    owner: "NCC / Urban Systems Lab"
    performance:
      validation_studies:
        - "case_study:city_A"
        - "case_study:city_B"
      known_biases:
        - "Overestimates disruption where informal backup generation is widespread"
    intended_use:
      - "NRM.flood.urban.infrastructure"

playbooks:
  anticipatory:
    - id: "aap.coastal_flood_preposition.v1"
      triggers:
        - index_id: "idx.coastal_flood_exposure.v1"
          condition: "expected_inundation_depth > 0.5m AND lead_time_days >= 3"
      actions:
        - "preposition_mobile_pumps"
        - "secure_substations"
        - "temporary_flood_barriers"
      governance:
        required_quorum_profile: "nvm.3of6.gov-infra-community.v1"
        hil_required: true
  incident_response:
    - id: "irp.coastal_flood_response.v1"
      triggers:
        - index_id: "idx.urban_service_disruption.v1"
          condition: "service_disruption_score >= 0.7"
      actions:
        - "emergency_power_rerouting"
        - "prioritise_hospital_restoration"
        - "activate_urban_evacuation_routes"
      communication:
        channels:
          - "NXCOMMS.emergency_alerts"
          - "public_portal_dashboard"
      legal_links:
        clause_templates:
          - "clause.emergency_powers.infrastructure.v1"

dashboards:
  - id: "db.urban_cro.v1"
    role: "corporate_cro"
    description: "Portfolio-level view of coastal exposure and disruption risk"
    built_with: "PowerBI"
  - id: "db.municipal_em.v1"
    role: "municipal_emergency_manager"
    description: "City-level real-time operational view"
    built_with: "PowerBI"
  - id: "db.public_explainer.v1"
    role: "public"
    description: "Public-facing risk explainer with uncertainty ranges"
    built_with: "PowerBI"

connectors:
  - id: "conn.global_surge_api.v1"
    type: "api"
    target_system: "Global Surge Model Service"
  - id: "conn.national_infra_registry.v1"
    type: "db"
    target_system: "National Infrastructure Registry"

governance:
  review_cycle_years: 3
  advisory_committees:
    - "Coastal & Urban Systems Scientific Panel"
    - "Community & City Networks Advisory Group"
  conflict_of_interest_policy: "https://example.org/policies/nxpck/coastal-flood/coi"
  grf_certification_status: "certified"
  grf_certification_id: "grf.cert.nxpck.coastal-flood-urban.v1"

safety_overlays:
  automation_constraints:
    prohibited_actions:
      - "fully_automated_shutdown_of_citywide_grid"
    hil_required_for:
      - "critical_infrastructure_load_shedding"
  dual_use_constraints:
    model_restrictions:
      - model_id: "mdl.coastal_inundation.v1"
        prohibited_uses:
          - "military_targeting_planning"
  privacy_constraints:
    urban_vulnerability_maps:
      aggregation_min_population: 300
      disallow_sub-block_visualisation: true

testing:
  test_suites:
    - id: "ts.coastal_flood_sanity.v1"
      scope: "pipelines_and_indices"
    - id: "ts.coastal_flood_scenarios.v1"
      scope: "profiles_and_playbooks"
  ai_red_team_exercises:
    - "redteam.coastal_agent_misuse.v1"

meta:
  created_at: "2026-05-01T12:00:00Z"
  created_by: "GCRI/Coastal-Urban-Lab"
  last_updated_at: "2027-02-11T08:30:00Z"
  last_updated_by: "GRF/Climate-Infra-Committee"
  documentation_urls:
    - "https://example.org/docs/nxpck/coastal-flood-urban/v1"
```

These examples show how **Rails** and **Packs** encode, in machine-readable form:

* **Scope, governance, and lawful basis**
* **Semantic extensions (GRIx), pipelines, and models**
* **SLOs, safety envelopes, and NVM requirements**
* **Dashboards, playbooks, and capital linkages**

In practice, Appendix B can be extended with **minimalist examples**, **testing stubs**, and **validation schemas** (JSON Schema/OpenAPI) to support implementation, tooling, and education.


---

# 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/yaml.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.