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.

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).

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.