EarthSciSerialization

EarthSciML Serialization Format — A language-agnostic JSON-based format for earth science model components, their composition, and runtime configuration.

Overview

The ESM (.esm) format enables persistence, interchange, and version control for earth science models across multiple programming languages. Every model is fully self-describing: all equations, variables, parameters, species, and reactions are specified in the format itself, allowing conforming parsers in any language to reconstruct the complete mathematical system.

The format is language-agnostic (Julia, TypeScript, Python, Rust, Go), human-readable JSON, composable, validated, and supports rich mathematical expressions. See the format specification for details.

Quick Start

Loading an ESM Model

Julia:

using EarthSciSerialization
esm_file = load("model.esm")
println("Model has $(length(esm_file.models)) components")

TypeScript/Node.js:

import { load, validate } from 'earthsci-toolkit';
const esmFile = load('model.esm');
const result = validate(esmFile);

Python:

import earthsci_toolkit
esm_file = earthsci_toolkit.load("model.esm")
print(f"Model has {len(esm_file.models)} components")

Packages

This repository contains multiple language implementations of the ESM format:

Package	Language	Description	Directory
EarthSciSerialization.jl	Julia	Complete MTK/Catalyst integration	packages/EarthSciSerialization.jl/
earthsci-toolkit	TypeScript	Web/Node.js types and utilities	packages/earthsci-toolkit/
earthsci_toolkit	Python	Scientific Python integration	packages/earthsci_toolkit/
earthsci-toolkit	Rust	High-performance implementation	packages/earthsci-toolkit-rs/
esm-format-go	Go	Lightweight Go implementation	packages/esm-format-go/
esm-editor	SolidJS	Interactive web-based editor	packages/esm-editor/

Installation

Julia

using Pkg
Pkg.add("EarthSciSerialization")

TypeScript/Node.js

npm install earthsci-toolkit

Python

pip install earthsci-toolkit

Rust

[dependencies]
earthsci-toolkit = "0.1.0"

Go

go get github.com/EarthSciML/EarthSciSerialization/packages/esm-format-go

Format Specification

The ESM format supports:

• Models: ODE-based model components with variables, parameters, and equations
• Reaction Systems: Chemical reaction networks with species and reactions
• Coupling: Rules for composing multiple model components
• Domain: Spatial and temporal domain specifications
• Operators: Registered mathematical operators and data loaders
• Metadata: Authorship, provenance, and documentation

Example ESM File

{
  "esm": "0.1.0",
  "metadata": {
    "name": "SimpleChemistry",
    "description": "Basic atmospheric chemistry model",
    "authors": ["Chris Tessum"]
  },
  "models": {
    "chemistry": {
      "variables": [
        {
          "name": "O3",
          "description": "Ozone concentration",
          "units": "molec/cm^3",
          "initial": 1e12
        }
      ],
      "equations": [
        {
          "lhs": {
            "op": "D",
            "args": ["O3", "t"]
          },
          "rhs": {
            "op": "-",
            "args": [
              {
                "op": "*",
                "args": ["k1", "O3"]
              }
            ]
          }
        }
      ]
    }
  }
}

Documentation

• Format Specification — Complete ESM format documentation
• Library Specification — Requirements for ESM library implementations
• Schema Reference — Authoritative JSON schema
• Conformance Spec — Fixture format, execution protocol, CI integration, and run commands
• Validation Matrix — Reference taxonomy of testable requirements

Contributing

We welcome contributions! This project uses:

• Beads for issue tracking and project management
• Julia testing with julia --project=. -e 'using Pkg; Pkg.test()'
• Cross-language conformance tests to ensure implementation consistency

Testing the Conformance Infrastructure

# Run full conformance tests (requires working language implementations)
./scripts/test-conformance.sh

See individual package directories for language-specific development guides.

License

This project is licensed under the MIT License.

Citation

If you use EarthSciSerialization in your research, please cite:

@software{earthsciserialization,
  title = {EarthSciSerialization: Language-agnostic serialization for earth science models},
  author = {Chris Tessum and contributors},
  year = {2026},
  url = {https://github.com/EarthSciML/EarthSciSerialization}
}