HydroModelSpec: Toward Standardized Machine Learning Model Exchange in Hydrology

Nikhil Singh, Ramteja Sajja, Yusuf Sermet, Ibrahim Demir

The rapid growth of deep learning models for hydrological forecasting (e.g., CNNs, LSTMs, Transformers) has created a fragmented ecosystem where trained models remain tied to their original frameworks, environments, and institutions. Despite substantial investments in model development, the hydrological community lacks a generalized structure for packaging models with their architecture, training provenance, I/O schema, performance benchmarks, and execution requirements into a portable, verifiable format that facilitates sharing and reproducibility. This study presents HydroModelSpec, a vendor-neutral, open-source, JSON Schema-based framework for encoding, validating, and exchanging hydrological machine learning models. Building on established practices in model documentation and metadata standards, the framework organizes model exchange through a layered architecture: a Core Schema for universal metadata, Domain Profiles for task-specific constraints (e.g., streamflow post-processing, water level forecasting, flood inundation, reservoir operations), Portable Document Types (including Model Cards, Execution Manifests, and Benchmark Reports) for contextualizing artifacts, and a Validator for enforcing structural and semantic conformance. The framework also incorporates a privacy attestation component, supporting trust-verified model sharing in regulated environments where training data cannot leave the originating device. By providing a standardized structure through which hydrological researchers and agencies can share trained models without sharing raw data, HydroModelSpec aims to lower the barriers to reproducibility, interoperability, and collaborative model development across the hydrological sciences.