oicp-kit 0.1.0

OICP (Open InterCharge Protocol) toolkit for EV roaming through Hubject: spec-exact typed models for OICP 2.3, mTLS client, axum server, EVSE delta sync, CDR pre-flight and a Hubject broker simulator.
Documentation

oicp-kit

CI crates.io docs.rs license

A Rust toolkit for OICP (Open InterCharge Protocol), the protocol that carries EV roaming traffic between Charge Point Operators (CPO) and e-Mobility Providers (EMP) through the Hubject brokering system.

Unlike OCPI, which is peer-to-peer, OICP is hub-and-spoke: every partner talks only to Hubject, over mutual TLS — and Hubject calls back into the partner for the reverse direction. Both halves are needed to go live, and this crate ships both, along with the pieces that are hard to get right: an EVSE delta-sync engine, a CDR pre-flight, and MockHubject — a complete brokering system in a process, so you can integrate before you have onboarded.

cargo add oicp-kit

The five properties that decide quality

Energy and money are never floats. OICP defines ConsumedEnergy as MeterValueEnd - MeterValueStart, and every one of those numbers ends up on an invoice between two companies. In f64, 10.1 - 0.1 is 10.000000000000002; here it is 10.0, because every OICP number is an exact decimal (rust_decimal::Decimal behind types::Number) and every sum, difference and comparison in the crate is decimal arithmetic. cargo run -p xtask -- no-floats fails CI on an f32 or f64 anywhere in src/, with one exemption it prints by name: the JSON boundary in types::Number, exact for every value OICP carries and reported by Number::json_round_trips where it would not be.

Identifiers are parsed, and the wire form survives. Every OICP identifier accepts two grammars — ISO 15118 and DIN SPEC 91286 — and Hubject compares the one in your URL against your TLS client certificate as text, answering a mismatch with 017 Unauthorized Access.

use oicp_kit::types::EvseId;

let a: EvseId = "DE*AB7*E840*6487".parse()?;   // ISO, separated
let b: EvseId = "DEAB7E8406487".parse()?;      // ISO, packed

assert_eq!(a, b);                              // the same charging spot…
assert_eq!(a.to_string(), "DE*AB7*E840*6487"); // …each written back exactly as it arrived
assert_eq!(a.operator_id(), b.operator_id());  // …and Hubject's own routing rule, for free
# Ok::<(), oicp_kit::types::IdError>(())

Parsing and conformance are separate questions. A PullEvseData page carries thousands of records from dozens of operators. One operator's malformed HotlinePhoneNumber cannot make the page undecodable — the value arrives, and Validate::validate reports it with an RFC 6901 JSON Pointer into the JSON the peer actually sent:

# use oicp_kit::testkit::samples;
# let mut value = serde_json::to_value(samples::pull_evse_data_record("DE*ABC*E1")).unwrap();
# value["HotlinePhoneNumber"] = serde_json::json!("call us");
# let json = serde_json::to_string(&value).unwrap();
use oicp_kit::emp::PullEvseDataRecord;
use oicp_kit::types::Validate;

let record: PullEvseDataRecord = serde_json::from_str(&json)?;   // permissive
for violation in record.validate().unwrap_err().iter() {
    println!("{} [{}]: {}", violation.pointer, violation.code, violation.message);
    // /HotlinePhoneNumber [pattern_mismatch]: "call us" is not a '+' followed by 5 to 15 digits
}
# Ok::<(), Box<dyn std::error::Error>>(())

The rule throughout is parse permissively, validate explicitly, construct strictly — every builder's build() returns Result<T, Violations>, so an object this crate emits is conformant by construction. build_unchecked() exists, and says what it is.

"Conformant" is stricter than "it parses". A field whose notation has a grammar is checked against that grammar: GeoCoordinates has one regular expression per notation, so "52" is not a decimal degree (OICP has no notation for a whole number of degrees) and "9°21'39''" is not a DMS coordinate (the seconds' fractional part is not optional). Both read fine as numbers.

One malformed record does not cost the page either. A crawl decodes the page envelope first and each record on its own, so a PullEvseData over a European data set loses one charging point rather than every charging point after it — and says which:

# use oicp_kit::client::CrawlError;
# use oicp_kit::emp::PullEvseDataRecord;
# fn store(_: PullEvseDataRecord) {}
# fn handle(item: Result<PullEvseDataRecord, CrawlError>) {
match item {                                  // …for each item the crawl yields
    Ok(record) => store(record),
    Err(error) => eprintln!("{error}"),       // record 812 on page 39, and the crawl goes on
}
# }

Nothing a peer sent is thrown away. OICP 2.3 is a terminal version that Hubject nonetheless edits in place, with no version bump. Undocumented fields land in types::Extensions and are written back verbatim; an enum value this crate has never seen keeps its text in a Custom variant and is still reported by validate(). A hub built on this crate forwards next year's field intact.

Both directions, one trait each. Four OICP operations are marked "To RECEIVE" in the CPO document, and one of them is "Implementation: MANDATORY". Most implementations ship the client half and leave Hubject's callbacks as an exercise — so a driver's phone app cannot start a session. Here the CPO role is one client and one trait, and if it compiles, your Hubject-facing surface is complete.

What is in the box

Layer Feature What it gives you
types (always) ID grammars (ISO + DIN), Number, Extensions, RFC 6901 validation, the errata registry
cpo cpo the CPO half of the OICP 2.3 wire model — pushes, authorization, CDRs, notifications, pricing
emp emp the EMP half — pulls, pagination, CDR retrieval, authentication data
transport transport the endpoint table (service × version → path), page envelope, error mapping
client client async client over reqwest with mutual TLS, streaming crawls, safe retries
server server axum router per role, driven by one trait — the Hubject-facing half
sync sync the LastCall delta engine, and the minimal-push planner
eichrecht eichrecht typed calibration-law data, and CDR pre-flight
testkit testkit samples, MockHubject, and the onboarding scenarios as runnable checks
schema schema JsonSchema for every wire type
oicp CLI cli validate, id, cdr, open, endpoints, scenarios, errata, defects, schema, serve-mock, pull

Default features are cpo, emp and transport. full turns on everything except the CLI.

MockHubject: integrate before you onboard

Testing against the real brokering system needs a signed contract, certificates issued by Hubject's CA and access to their QA environment — weeks before the first request. And the failures that cost time are sequences, not single messages.

use oicp_kit::testkit::{MockHubject, MockEmp, samples};
use oicp_kit::types::Code;

let mut hubject = MockHubject::new();
hubject.register_emp(MockEmp::permissive("DE-DCB".parse()?));
hubject.push_evse_data(&samples::evse_data_record("DE*ABC*E1").into())?;

// A driver swipes a card; the broker routes it to the EMP that owns the contract.
let response = hubject.authorize_start(&samples::authorize_start_request("DE*ABC*E1"));
let session = response.session_id.clone().unwrap();

// A CDR for a session the broker opened settles…
assert!(hubject.submit_cdr(&samples::charge_detail_record("DE*ABC*E1", session)).is_ok());

// …and one for a session it did not is refused, exactly as the real broker refuses it.
let invented = samples::charge_detail_record("DE*ABC*E1", samples::session_id());
assert_eq!(*hubject.submit_cdr(&invented).unwrap_err().code(), Code::SessionIsInvalid);
# Ok::<(), Box<dyn std::error::Error>>(())

The broker also enforces the two rules that need session state, which no validate() can see:

  • One CDR per SessionID. A submission that times out gets resubmitted; the real broker refuses the second. A mock that accepts both teaches a reconciliation to count acknowledgements instead of sessions, and that is how a session's revenue gets counted twice.
  • A session is stopped with the medium that started it — "the session MUST only be stopped with the same medium, which was used for starting the session".

testkit::scenarios::run_all() packages the sequences Hubject walks partners through at onboarding, both of these among them, so the paid integration test is not the first time you see them.

The delta engine

Every EMP rebuilds the same fragile logic: full pull, then periodic LastCall deltas, applying insert/update/delete. Five rules are easy to get wrong and expensive to get wrong quietly:

  1. LastCall is exclusive with the filters. A delta scoped to a country silently omits charge points that moved out of it, and those stale records live forever.
  2. A delete is a tombstone. Applying it as an upsert leaves a corrupted half-record behind.
  3. The watermark advances on success, not on request. Move it early and a failed page's changes are lost permanently — the next delta starts after them.
  4. Deltas expire. After a long outage a delta cannot be trusted and the copy must be rebuilt.
  5. LastCall is read by Hubject's clock and written by yours. A machine running a minute fast asks for changes since an instant Hubject has not reached, and everything in that minute is never sent again. The watermark is therefore committed with a skew guard — five minutes by default — which costs a small overlap the engine applies idempotently.

sync::Planner encodes all five, and a property test proves the thing that matters:

applying any sequence of deltas leaves the same state as a full pull.

# use oicp_kit::sync::{InMemoryEvseRepository, Planner, PlannerConfig};
# use oicp_kit::types::GeoCoordinatesFormat;
# fn main() -> Result<(), Box<dyn std::error::Error>> {
# let mut repository = InMemoryEvseRepository::new();
# let planner = Planner::new(PlannerConfig::new("DE-DCB".parse()?, GeoCoordinatesFormat::Google));
// `begin` decides the pull *and* empties the copy when the answer is a full one — a full pull is
// the whole world, so what is not in it has been withdrawn.
let (plan, watermark) = planner.begin(&mut repository)?;
// …crawl every page of plan.request() and apply it…
planner.commit(&mut repository, watermark)?;   // only now
# Ok(())
# }

The CPO has the mirror problem, with a sharper edge: ActionType::FullLoad replaces everything Hubject holds for the operator, so a nightly job with one wrong filter withdraws a fleet from the roaming network. sync::PushPlanner computes the minimal insert/update/delete set, and fullLoad is a separately named method that says what it does.

CDR pre-flight

Hubject rejects an inconsistent CDR after the fact, when the session is long over and the sale is written off. Several of the reasons cannot be seen from the CDR alone:

# use oicp_kit::testkit::samples;
# use oicp_kit::types::CalibrationLawDataAvailability;
# let mut evse = samples::evse_data_record("DE*ABC*E1");
# evse.calibration_law_data_availability = CalibrationLawDataAvailability::External;
# let cdr = samples::charge_detail_record("DE*ABC*E1", samples::session_id());
use oicp_kit::eichrecht::CdrCheck;

let findings = CdrCheck::new()
    .against_evse(&evse)                        // the calibration-law and plausibility rules
    .with_known_products(["AC 1", "DC"])        // the tariff the EMP will be billed under
    .run(&cdr);

for finding in &findings {
    println!("{finding}");
    // [error] /SignedMeteringValues: DE*ABC*E1 reports CalibrationLawDataAvailability 'External',
    //         which makes SignedMeteringValues mandatory on every CDR from it; …
}

Where Hubject's own documents disagree

OICP 2.3 is published as four documents that describe one protocol, and they do not agree. Each conflict is recorded in types::ERRATA with what breaks and which spelling this crate emits — and cargo run -p xtask -- errata checks that each is still a conflict upstream, so an erratum Hubject fixes fails CI rather than lingering as a stale claim.

Id Field The disagreement
OICP23-E001 ChargeDetailRecord.HubProviderID the EMP schema says HubProviderId; everything else says HubProviderID
OICP23-E002 EvseDataRecord.ChargingStationId the schema says …Id; every published example says …ID
OICP23-E003 ChargingFacility.Power Integer in the leading document and the CPO schema; unconstrained number in the EMP schema
OICP23-E004 GetChargeDetailRecords.CDRForwarded the property is CDRForwarder; the leading document and the file's own example say CDRForwarded
OICP23-E005 reservation EMPPartnerSessionID the reservation schemas say …Id; every other message says …ID
OICP23-E006 ChargingNotificationProgress.ChargingDuration the EMP document defines it in terms of itself

oicp-kit reads both spellings and writes the leading document's.

$ oicp errata

Command line

$ oicp id 'DE*AB7*E840*6487'
EvseID     DE*AB7*E840*6487
  standard ISO
  country  DE
  operator DE*AB7
  key      DEAB7E8406487

$ oicp validate cdr session.json
1 violation(s):
  /ConsumedEnergy
    [inconsistent] ConsumedEnergy is 99 but MeterValueEnd - MeterValueStart is 10.0; …

$ oicp cdr session.json --evse charging-point.json --products 'AC 1,DC'
$ oicp endpoints --role cpo --environment prod --id 'DE*ABC'
$ oicp defects                       # where OICP 2.3 is narrower than real hardware
$ oicp scenarios                     # the onboarding sequences, against an in-process broker
$ oicp serve-mock                    # …or the same broker on a socket
$ oicp pull --provider DE-DCB --url http://127.0.0.1:8080/api/oicp --snapshot ./snapshot.json

serve-mock prints the exact pull command to run against it. The /api/oicp is not decoration: every OICP endpoint hangs off it, and a base URL without it answers 404 on every call — which is why the client's HTTP error says so rather than just reporting the status.

Versions

OICP 2.3 is the version to target, and the last one. The release notes state that "From OICP 2.3 version only REST APIs are offered"; 2.1 was retired in April 2023 and 2.2 is superseded. In September 2025 Hubject joined the EVRoaming Foundation as a Full Contributor and committed to native OCPI support on intercharge, so there is no 2.4 — only in-place maintenance of 2.3, which is exactly what Extensions and the open enums are for.

OICP versions services, not the protocol: a "2.3 implementation" is evsepush/v23 and charging/v21 and cdrmgmt/v22 and reservation/v11 and dynamicpricing/v10 and notificationmgmt/v11. transport::Operation is the single place that knows which is which, and CI diffs it against Hubject's published OpenAPI documents.

Related crates

  • ocpp-kit — OCPP, the station ↔ CSMS protocol.
  • ocpi-kit — OCPI, peer-to-peer roaming.

Contributing

cargo test --all-features, cargo run -p xtask -- all and cargo run -p xtask -- features must pass. The last one builds each feature on its own with warnings denied: --all-features is exactly the build that cannot tell whether a feature declares what it needs, and the way that fails is a warning rather than an error.

The endpoints, errata and spec-sync checks read the Hubject specifications from specs/ (gitignored, because they are third-party publications); without them they skip rather than fail.

git clone https://github.com/hubject/oicp specs/oicp
git clone https://github.com/hubject/oicp-cpo-2.3-api-doc specs/oicp-cpo-2.3-api-doc
git clone https://github.com/hubject/oicp-emp-2.3-api-doc specs/oicp-emp-2.3-api-doc

cargo run -p xtask -- spec-sync --upstream asks Hubject's remotes whether the documents have moved since the pinned commits — no clone and no local specs/ needed. It runs weekly in CI, because Hubject edits the specification in place and nothing here changes when they do.

cargo run -p xtask -- seed-fuzz writes the fuzz corpus from this crate's own conformant messages and every identifier spelling the specification prints. The seeds are derived rather than committed, so re-run it after changing a wire type.

cargo run -p xtask -- seed-fuzz
cargo +nightly fuzz run wire        # …and identifiers, and delta

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

OICP is a protocol owned and maintained by Hubject GmbH. This project is not affiliated with Hubject. The specifications are published under CC BY-SA 4.0 and are not redistributed here.