Comparison: grid-coordination vs. ElaadNL OpenADR 3 Python libraries

[dcj]

After announcing python-oa3 and python-oa3-client to OpenADR 3 colleagues, we learned about a similar project: openadr3-client by ElaadNL. This discussion summarizes the two approaches.

The Projects

	python-oa3 + python-oa3-client	openadr3-client (ElaadNL)
Author	Clark Communications Corporation	ElaadNL (Dutch DSO research institute)
License	MIT	Apache-2.0 (REUSE compliant)
Python	3.10–3.13	3.12+ only
Spec versions	3.1.0	3.0.1 and 3.1.0
Architecture	Two-layer: low-level library + client framework	Single monolithic package
HTTP library	httpx	requests
Package count	2 (openadr3, openadr3-client)	1 (openadr3-client)
LOC	~2,500	~8,900

---

Design Philosophy

grid-coordination (python-oa3 stack) — Minimalist, composable, Clojure-influenced. Two distinct layers:

• python-oa3: Raw HTTP + Pydantic models with a novel two-layer entity system (raw camelCase wire format preserved alongside coerced snake_case typed models). Pendulum for time, Decimal for monetary values. Optional OpenAPI spec introspection for route/scope discovery.
• python-oa3-client: VEN/BL lifecycle, MQTT/webhook notification channels, mDNS/DNS-SD discovery. Delegates all API calls to python-oa3 via __getattr__.

ElaadNL (openadr3-client) — Enterprise-grade, comprehensive, single package. Emphasizes type safety and immutability:

• Frozen Pydantic models throughout (no accidental mutations)
• Creation guard pattern prevents duplicate resource creation
• Validator plugin system for domain-specific rules (e.g., GAC compliance)
• Pandas/pandera integration for data science workflows
• Interface/implementation separation (abstract base classes for VTN endpoints)

---

Key Differentiators

Aspect	grid-coordination	ElaadNL
Raw wire format	Preserved via ._raw PrivateAttr on every entity	Not preserved; models are the single representation
Time handling	Pendulum (Duration algebra, timezone conversion, VTN-RI quirk handling)	Standard datetime (no special library)
Monetary values	Decimal coercion for PRICE/USAGE payloads	No special numeric handling
Immutability	Mutable models	Frozen models (frozen=True)
Spec versions	3.1.0 only	3.0.1 and 3.1.0 (parallel implementations)
mDNS discovery	Yes (DNS-SD with _openadr3._tcp.)	No
Webhook receiver	Yes (Flask daemon thread)	No
MQTT	Via ebus-mqtt-client (optional extra)	Via paho-mqtt (optional extra)
Pandas integration	No	Yes (DataFrame ↔ intervals, pandera validation)
Plugin system	No	Yes (validator plugins for custom rules)
OpenAPI spec embedded	Yes (introspection for routes/scopes)	No spec in repo
VTN-RI compatibility	Explicit handling of non-spec quirks (snake_case MQTT, malformed datetimes)	No special VTN-RI handling noted
Testing	Unit tests with mocked HTTP (pytest-httpx)	Integration tests with Docker containers (testcontainers)
Tooling	pip/hatchling	uv/hatchling + ruff + mypy + bandit

---

Strengths by Project

grid-coordination strengths:

• Cleaner separation of concerns (library vs. client framework)
• Broader Python version support (3.10+)
• VTN-RI battle-tested (handles real-world spec deviations)
• mDNS discovery and webhook receiver — more complete notification story
• Raw wire format preservation (debugging, round-tripping)
• Pendulum gives richer time algebra than stdlib datetime
• Lighter footprint (~2.5K LOC vs ~9K)

ElaadNL strengths:

• Dual spec version support (3.0.1 + 3.1.0) with separate model trees
• Frozen models prevent an entire class of mutation bugs
• Creation guard prevents accidental duplicate resource creation
• Validator plugin architecture for extensible domain rules
• Pandas integration for data science / analytics use cases
• Heavier test infrastructure (real containerized VTNs)
• REUSE license compliance (SPDX headers on every file)
• More established CI/quality toolchain (mypy, bandit, ruff)

---

Overlap and Potential Collaboration

Both projects:

• Are manually written (not code-generated)
• Use Pydantic v2 for models
• Use Hatchling for packaging
• Support OAuth2 client credentials
• Cover BL and VEN client roles
• Support MQTT notifications
• Are alpha-stage

The biggest complementary gaps: grid-coordination has mDNS + webhooks + VTN-RI quirk handling that ElaadNL lacks; ElaadNL has 3.0.1 support + pandas + plugin validation that grid-coordination lacks. There’s a reasonable argument for convergence on the model layer while keeping client-level features as optional extras.

---

Feedback and corrections welcome — especially from the ElaadNL team if they spot inaccuracies.