OCPI 2.2 vs 2.2.1 Differences: Every Change and When to Upgrade

OCPI 2.2.1 came out as a maintenance release on top of OCPI 2.2. The third digit tells you what to expect: fixes and refinements, not a new feature set. It is the spec authors saying “here is what 2.2 got slightly wrong, and here are a few small things it was missing” — not introducing major new capabilities.

There is one persistent myth worth killing up front: 2.2.1 did not add the NAP, NSP, or SCSP roles. Those roles arrived in 2.2. If a colleague tells you 2.2.1 is “the release that added the new roles,” they are remembering the wrong version. What 2.2.1 actually changed is a short, concrete list of data-model tweaks — and this article walks through every one, what stayed the same, and whether you need to move.

The character of the release

OCPI’s second-digit versions (2.0, 2.1, 2.2, 2.3) introduce new modules, roles, and reshaped data contracts. Third-digit releases (2.1.1, 2.2.1) fix errors and add small refinements without breaking the version they patch. If you want the full timeline, see the OCPI version history; for a grounding in the protocol itself, start with what OCPI is and why it exists; and if you are weighing OCPI against its neighbors, see OCPI vs OCPP vs ISO 15118.

OCPI 2.2.1 specifically delivers:

• A handful of new optional fields on existing objects (CDR, CdrToken, CdrLocation).
• Additional enum values on Connector (ConnectorType and PowerType).
• One small command-level addition (connector_id on StartSession).
• Corrections to descriptions and examples, most notably around tariff step_size.

It does NOT introduce new modules. It does NOT add or remove roles. It does NOT change authentication, endpoint URLs, or the fundamental data contracts. It does NOT break wire compatibility with well-written 2.2 implementations.

What actually changed in 2.2.1

The real changelog is short and specific. These are the substantive items; you can read the full list in the spec’s own version history document.

CDR and billing refinements

The CDR (Charge Detail Record) module — the final billing record for a session — got the most attention:

• country_code and party_id added to CdrToken. The token that identifies the driver inside a CDR now carries the owning party, which removes ambiguity when the same token id could exist under different eMSPs.
• state added to CdrLocation, and postal_code made optional. This directly helps North American CPOs: a US or Canadian address needs a state or province, and not every jurisdiction supplies a postal/ZIP code cleanly. A network like Electrify America or FLO fits the address model more naturally than it did under 2.2.
• CDR SignedData length increased (to 5000) and the signed-data field types tightened to strings. Longer, well-typed signed meter values — the cryptographically signed readings used for Eichrecht-style calibration-law compliance in Germany and beyond.
• Optional home_charging_compensation field added to CDR. Supports reimbursement flows where a driver charges at home and the cost is settled back through the eMSP.

Connector enum additions

The Connector object gained new enum values so it can describe more hardware faithfully:

• AC_2_PHASE and AC_2_PHASE_SPLIT added to PowerType. Split-phase AC is common in North American residential and light-commercial wiring, so this matters for J1772 AC deployments on 240 V split-phase service far more than it does in most of Europe.
• Additional ConnectorType values. The enum was extended to cover connector standards that were missing or under-represented in 2.2.

If you maintain a strict allow-list of enum values, this is the one change most likely to bite: a 2.2.1 partner can now legitimately send a PowerType or ConnectorType your 2.2 code has never seen. Reject-on-unknown code will fail on perfectly valid data.

A command-level addition

• connector_id added to the StartSession command, with a matching START_SESSION_CONNECTOR_REQUIRED capability on the EVSE. Some hardware needs to be told which connector to energize when an EVSE has more than one. 2.2.1 lets a CPO advertise that requirement (via the capability) and lets the eMSP satisfy it (by supplying the connector id in the remote-start command).

Documentation and example fixes

• Clearer descriptions and examples, especially for tariff step_size. step_size controls how usage is rounded up into billable units, and the 2.2 wording caused real interop disagreements over pricing. The 2.2.1 text pins down the intended behavior.
• A datatype fix on the CDR SignedData URL and assorted editorial corrections.

These items do not change the protocol’s shape; they remove ambiguity and let implementations agree on the same interpretation.

What did NOT change

A short list of things people often assume changed in 2.2.1 but did not:

• Roles. No new roles. CPO, eMSP, Hub, NAP (National Access Point), NSP (Navigation Service Provider), and SCSP (Smart Charging Service Provider) were all already defined in 2.2. This is the single most common misconception about 2.2.1.
• Module set. No new modules. Still the same set as 2.2, including HubClientInfo and ChargingProfiles, both introduced in 2.2.
• Core data model. Existing object structures are intact; 2.2.1 adds optional fields and enum values rather than restructuring anything.
• Endpoint URLs. Same URL conventions as 2.2 (/ocpi/{role}/2.2.1/..., with the version segment being the only visible difference).
• Authentication. Same Token-scheme bearer model and the same token A / B / C registration handshake carried over from the 2.1.1-to-2.2 migration.
• Transport. Still HTTPS with JSON bodies.

If your 2.2 code is solid, your 2.2.1 code will look almost identical.

Migration cost

For a well-implemented 2.2 codebase, moving to 2.2.1 is small — usually a few days of focused work rather than a project. The work concentrates in a few places:

• Accept and emit the new optional CDR fields (home_charging_compensation) and the CdrToken country_code / party_id fields.
• Handle the CdrLocation state field and treat postal_code as optional.
• Widen any enum handling so new ConnectorType and PowerType values (including AC_2_PHASE and AC_2_PHASE_SPLIT) pass validation instead of being rejected.
• Support connector_id on StartSession, and advertise START_SESSION_CONNECTOR_REQUIRED where the hardware needs it.
• Update your tariff logic and tests to match the clarified step_size semantics.

Testing: exercise a CDR round-trip with the new fields populated, send and accept a StartSession that carries connector_id, and confirm your validator tolerates unfamiliar enum values from a partner.

Coordination: advertise 2.2.1 on your Versions endpoint after testing with one partner. Because the wire format is a near-superset of 2.2, most partners will not notice the difference.

When 2.2.1 matters most

A few scenarios where moving to 2.2.1 has real, immediate value. The decision usually comes down to a handful of questions:

flowchart TD
    A[On OCPI 2.2?] --> B{Handle CDRs for<br/>US/Canada addresses?}
    B -->|Yes| U[Move to 2.2.1 soon]
    B -->|No| C{Need split-phase or<br/>new connector types?}
    C -->|Yes| U
    C -->|No| D{Multi-connector EVSEs<br/>needing StartSession<br/>connector_id?}
    D -->|Yes| U
    D -->|No| E[Fold into next<br/>maintenance cycle]
    style U fill:#e8f5e9,stroke:#2e7d32
    style E fill:#fff3e0,stroke:#ef6c00

You bill sessions with North American addresses. The state field and optional postal_code on CdrLocation make US and Canadian CDRs cleaner — helpful for CPOs and eMSPs working with networks like ChargePoint, Electrify America, or FLO.

You deal with split-phase AC or newer connector standards. If your fleet includes 240 V split-phase AC hardware or connector types the 2.2 enum did not name, the extended PowerType and ConnectorType values in 2.2.1 let you describe them accurately instead of forcing a poor fit.

You operate multi-connector EVSEs that must be told which plug to energize. connector_id on StartSession plus the START_SESSION_CONNECTOR_REQUIRED capability exist precisely for this.

You care about signed-meter or home-charging settlement. The larger signed-data length supports calibration-law compliance (relevant for German Eichrecht and similar regimes), and home_charging_compensation supports reimbursing home charging through the eMSP.

You’re starting fresh on OCPI 2.x. If you’re choosing between implementing 2.2 and 2.2.1, do 2.2.1. Same effort; corrected baseline.

When 2.2.1 doesn’t matter much

Conversely, you can defer 2.2.1 if:

• You roam with one or two partners who are stable on 2.2 and not pushing for it.
• Your CDRs are all in regions where the 2.2 address model already works and you have no split-phase or exotic-connector hardware.
• You have no multi-connector remote-start requirement and no signed-meter or home-charging settlement need.

In those cases, 2.2.1 is safe to leave for a future maintenance cycle — just make sure your validators tolerate the new enum values a partner might send.

The path forward: 2.2.1 → 2.3

OCPI 2.3.0 is the next second-digit step and is now a published release. It is a larger change than 2.2.1: unlike a maintenance release, it extends the protocol’s capabilities rather than just correcting the previous version. For the authoritative list of what 2.3 adds and how it differs, follow the official changelog and release notes rather than any second-hand summary — see what’s new in OCPI 2.3.0, the OCPI version history, and the spec’s own release page.

Deployment lags the spec, as it always does in roaming: a version being published is not the same as your partners and hubs supporting it. Most of the installed base is still on 2.2 / 2.2.1, so those remain the practical interop baseline for now, with 2.3 adoption following as partners and hubs enable it. OCPI 3.0 is being developed separately by the EVRoaming Foundation; there is no public production timeline for it, so treat any specific 3.0 date you see as speculation.

The practical takeaway: get to 2.2.1 as your clean 2.x baseline, keep your enum and field handling tolerant, and watch the changelog for when your partners actually turn on 2.3.

Key takeaways

• 2.2.1 is a maintenance release, not a feature release. It fixes and refines 2.2 without breaking it.
• It did NOT add roles. CPO, eMSP, Hub, NAP, NSP, and SCSP all came in 2.2. If someone tells you otherwise, they’re conflating the versions.
• The real changes are small and concrete: CDR/CdrToken/CdrLocation field additions (helpful for North American addresses and home-charging settlement), extended ConnectorType and PowerType enums (including split-phase AC), connector_id on StartSession, and clearer tariff step_size wording.
• Migration is a few days, and the biggest real-world risk is enum validators that reject the new, valid values a 2.2.1 partner may send.
• Starting fresh? Implement 2.2.1, then track the OCPI version history for 2.3 as your partners adopt it.

OCPI 2.2.1 is the spec authors closing the loop on 2.2 — correcting fields, extending a few enums, and pinning down the wording that caused interop arguments. It’s not exciting. It’s also the version you want as your baseline. The cost of moving is small, and the cleanup is real.