Crate ocpi_kit 

A toolkit for the OCPI (Open Charge Point Interface) protocol used for EV roaming between Charge Point Operators, e-Mobility Service Providers and roaming hubs.

What is here

Layer	Feature	What it gives you
types	(always)	CiString, DateTime, Number, Url, Extensions, validation
v2_3_0	v2_3_0	the OCPI 2.3.0 wire model, all ten modules
v2_2_1	v2_2_1	the OCPI 2.2.1 wire model
v2_1_1	v2_1_1	the OCPI 2.1.1 wire model
convert	convert	Upgrade/Downgrade between versions, with loss accounting
transport	transport	envelope, headers, credentials tokens, pagination, routing, PATCH
client	client	an async client over reqwest, with the registration handshake
server	server	an axum router driven by one trait per module and interface
hub	hub	routing, broadcast push, open routing, GET All, version bridging
tariffs	tariffs	an auditable pricing engine over CDRs and Sessions
testkit	testkit	sample objects, in-memory stores and a conformant mock peer

Four properties worth knowing about

Money is never a float. Every number in every object is a types::Number, an exact decimal. No public field of any OCPI object in this crate is an f32 or f64, and the modules where money is computed deny floats by lint.

Nothing a peer sent is thrown away. Undocumented JSON fields land in types::Extensions and are written back verbatim; an open-enum value this crate does not know keeps its text in a Custom variant. A hub built on ocpi-kit forwards a vendor extension it has never seen without damaging it, which is what OCPI 2.3.0’s extensibility chapter asks for.

Parsing and conformance are separate questions. A peer that overruns a string(45) cannot make a whole page of Locations undecodable; the value arrives, and types::Validate::validate reports it with a JSON Pointer. See types::validate.

The peer’s OCPI version is not your problem. client, server and hub speak the canonical v2_3_0 model and translate at the wire, so a 2.2.1 peer — most of the market — reads and writes as 2.3.0 objects, and anything that cannot cross is reported rather than dropped. See convert.

Getting started

use ocpi_kit::types::Validate;
use ocpi_kit::v2_3_0::locations::Location;

let json = std::fs::read_to_string("fixtures/2.3.0/location_example.json")?;
let location: Location = serde_json::from_str(&json)?;

assert_eq!(location.country_code.as_str(), "BE");
location.validate()?; // every length limit and cross-field rule of the spec

Spec traceability

Every public item carries a Spec: <version> §<anchor> line naming the AsciiDoc anchor in the OCPI source it implements, so a reviewer — or a partner’s compliance team — can go from a Rust type straight to the sentence that defines it.

Further reading

The guide covers the concepts behind these APIs — the parse/validate/construct rule, open enums, extensions, version bridging — plus per-layer walkthroughs, the interop quirks registry and the specification errata.

OCPI is a protocol owned and maintained by the EVRoaming Foundation. This project is not affiliated with the EVRoaming Foundation.

Modules

clientclient

An async OCPI client: registration handshake, typed module clients, paginated crawls.

convertconvert

Carrying objects between OCPI versions, with an explicit account of what was lost.

hubhub

A roaming hub: routing, broadcast push, open routing, GET All, and version bridging.

serverserver

An OCPI server: one trait per module and interface, mounted onto an axum::Router.

tariffstariffs

An auditable pricing engine: what a charging session costs, and exactly why.

testkittestkit

Building blocks for testing an OCPI integration: sample objects and in-memory stores.

transporttransport

Everything between the JSON and the HTTP: envelope, status codes, headers, credentials tokens, pagination, routing, endpoint URLs, PATCH and per-peer quirks.

types

The scalar and leaf types the whole specification is built from.

v2_1_1v2_1_1

The OCPI 2.1.1 wire model: the legacy version, and still in the field.

v2_2_1v2_2_1

The OCPI 2.2.1 wire model, described as a delta from v2_3_0.

v2_3_0v2_3_0

The OCPI 2.3.0 wire model: the canonical model of this crate.

Macros

ocpi_enum

Defines a closed OCPI enum: a fixed set of strings, where anything else is an error.

ocpi_lenient_enum

Defines an enum the specification declares closed, but which this crate still accepts unknown values for — and reports them.

ocpi_open_enum

Defines an OCPI OpenEnum: known values plus a Custom variant that preserves anything else.

Enums

InterfaceRole

Which side of a module’s data flow an endpoint implements.

ModuleId

The identifier of an OCPI module, as used in Endpoint.identifier.

VersionNumber

A version of the OCPI protocol, as it appears in /versions and in version details.

Constants

CANONICAL_VERSIONv2_3_0

The version of OCPI this crate treats as canonical: every other version is described as a delta from it.