OCPI 2.3.0 - Changelog
Complete changelog documenting all changes across OCPI versions, from 2.1.1 through 2.3.0-booking-1.0. Includes detailed impact assessments for eMSP and CPO implementations, covering module additions, field changes, type modifications, and specification corrections.
1. Overview
Chapter 19This chapter documents all changes made across OCPI versions, from OCPI 2.1.1 through to the latest 2.3.0-booking-1.0 release. Each section details the modifications, additions, and fixes introduced in each version transition, including their expected impact and effort for both eMSP and CPO implementations.
About This Chapter
Version Transitions
The changelog covers six major version transitions: 2.3.0 to 2.3.0-booking-1.0, 2.2.1-d2 to 2.3.0, 2.2.1 to 2.2.1-d2, OCPI 2.2 to 2.2.1, and OCPI 2.1.1 to 2.2. Each transition is documented with detailed descriptions of what changed.
Impact Assessment
For the major version transitions (2.2 to 2.2.1 and 2.1.1 to 2.2), detailed tables provide the expected impact and effort for both eMSP and CPO implementations, helping teams plan their upgrade path.
Module-Level Changes
Changes are categorized by module (Locations, Sessions, CDRs, Tariffs, Tokens, Commands, etc.) and object, making it easy to identify which parts of your implementation need updating.
Backwards Compatibility
Each change notes whether it involves field renames, type changes, new required fields, or entirely new modules, so implementers can assess backwards compatibility implications.
Version Timeline
The OCPI protocol has evolved through the following major versions covered in this changelog:
2. Changes between 2.3.0 and 2.3.0-booking-1.0
19.1This section documents the single change introduced between OCPI 2.3.0 and the 2.3.0-booking-1.0 revision.
Bookings Module Addition
New Module: The Bookings module has been added on top of OCPI, enabling advance reservation of charging slots through the protocol.
Add new Bookings module — added module on top of OCPI
3. Changes between 2.2.1-d2 and 2.3.0
19.2The transition from OCPI 2.2.1-d2 to 2.3.0 introduced significant new capabilities including protocol extensibility, parking objects, accessibility features, tax support, and new modules.
Extensibility
Make OCPI Extensible: possible to add modules, fields, enum values for certain enums
Parking & EVSEs
Add a Parking object linked to EVSEs, indicating vehicle type among other properties
Add a field to the EVSE object to indicate which eMSPs' contracts are accepted
Add a field to the Location object for a support telephone number
Accessibility & Compliance
Information for people with disabilities
Tax & Regional Support
Support for North American taxes
Take straightforward enum values from the OCPI 3.0 draft, including those that signal 15118 compatibility
Credentials & New Modules
Add new field in Credentials to give hub party ID and make hub clients be reported as normal credentials roles
Add new Payments module — added module on top of OCPI
4. Changes between 2.2.1-d2 and 2.3.0
19.3Complete list of all changes between OCPI 2.2.1-d2 and 2.3.0, including the Bookings module addition. This section represents the full cumulative diff.
All Changes
Make OCPI Extensible: possible to add modules, fields, enum values for certain enums
Add a Parking object linked to EVSEs, indicating vehicle type among other properties
Add a field to the EVSE object to indicate which eMSPs' contracts are accepted
Add a field to the Location object for a support telephone number
Information for people with disabilities
Support for North American taxes
Take straightforward enum values from the OCPI 3.0 draft, including those that signal 15118 compatibility
Add new field in Credentials to give hub party ID and make hub clients be reported as normal credentials roles
Add new Payments module — added module on top of OCPI
Add new Bookings module — added module on top of OCPI
5. Changes between 2.2.1 and 2.2.1-d2
19.4The 2.2.1-d2 revision focused primarily on documentation corrections, clarifications, and fixing inconsistencies found in the 2.2.1 specification. These changes improve the accuracy and usability of the documentation.
Documentation & Examples
Removed note that advised against sharing Locations on which home charging reimbursement happens
Lots of editing and rewriting of Tariffs and step_size documentation
Updated examples and diagrams to use convention of not using trailing slashes on URLs
Updated example of a short finished session so that the total energy matches the energies of the charging periods
Removed stipulation that all charging_periods have a different Tariff from CDRs module, which contradicts other statements in the CDRs module description
Add a note clarifying Base64 usage in the Authorization header and use more precise wording to specify the Base64 encoding
Replaced 2.2 by 2.2.1 in example URLs and a few other places where 2.2 was used to mean the current version
Tariffs, CDRs & Tokens Fixes
Added missing forward slash in Tokens Receiver interface endpoint URL structure definition
Changed "Tariff Elements" to "Tariffs" in description of tariffs field in CDR object definition
Added country_code and party_id to CdrToken examples
Changed country_id to country_code in credentials explanation
Replaced copy-pasted text about charging profiles in ChargingPreferencesResponse description
Replaced "cpo" by "emsp" in example URL of receiver-side session module
Allowed eMSP to replace CPO-issued session IDs when exchanging charging profiles with an SCSP
Interface & Specification Corrections
Changed text to give more actionable advice on how to set the Interface role in the Endpoint object for the credentials module
Added an explanation of why the Tariffs module doesn't say anything about price rounding
Added a note that CPOs should avoid using physical hardware ids for EVSE.uid
Removed example about a free hour of parking that conflicts with spec
Changed "GET" to "PUT" in sequence diagram showing routing header usage with Broadcast Push
6. Changes between OCPI 2.2 and 2.2.1
19.5Lots of typos fixed and textual improvements.
The following changes to messages/objects etc.
Change Summary
Typo fixes and textual improvements throughout the specification
CDR-related changes including CdrToken, CdrLocation, and signed data improvements
Commands and Locations enhancements for OCPP 1.x compatibility
New connector types and power types for broader hardware support
Impact Table
| Context | Expected Impact | Expected Effort | Description |
|---|---|---|---|
| Status codes | Minor / Minor | Minimal / Minimal | Added 4000 Hub generic error |
| CDRs / CdrToken Class | Minor / Minor | Minor / Major | Added mandatory country_code and party_id fields to make sure that a CdrToken uniquely identifies a charge token |
| CDRs / CDR Object | Minor / Minor | Minimal / Minimal | Added home_charging_compensation optional field. |
| CDRs / CdrLocation Class | Minor / Minor | Minimal / Minimal | Changed postal_code to optional, inline with the Location module. Added state as optional field, inline with the Location module. |
| CDRs / SignedData Class | Major / Minor | Minimal / Minimal | Changed public_key to string, was CiString |
| CDRs / SignedValue Class | Major / Major | Minimal / Minimal | Increased signed_data length from 512 to 5000. Changed plain_data to string, was CiString. Changed signed_data to string, was CiString. Changed url to string, was CiString. |
| Commands / StartSession Object | Minor / Minor | Medium / Minimal | Added optional field: connector_id to support OCPP 1.x Charge Points with multiple connectors per EVSE. |
| Locations / Capability Enum | Minor / Minor | Medium / Minimal | Added START_SESSION_CONNECTOR_REQUIRED to support OCPP 1.x Charge Points with multiple connectors per EVSE. |
| Locations / ConnectorType Enum | Minor / Minor | Minimal / Minimal | Added NEMA, GB/T, ChaoJi and Domestic M, N and O connector types. |
| Locations / PowerType Enum | Minor / Minor | Minimal / Minimal | Added AC_2_PHASE and AC_2_PHASE_SPLIT to the enum to support two phase chargers. |
7. Changes between OCPI 2.1.1 and 2.2
19.6Lots of typos fixed and textual improvements. Improved/fixed all descriptions and examples with relation to the Tariff step_size.
The following changes to messages/objects etc.
Change Summary
CDR Module Overhaul
New fields for ownership identification, Credit CDR support, signed meter data for Eichrecht, and detailed cost breakdowns.
New Modules
Added ChargingProfiles module for Smart Charging and HubClientInfo module for Hub-based routing information.
Commands Module Improvements
New CancelReservation command, improved result handling with CommandResult object, and case-insensitive identifiers.
Session, Location, Tariff, Token & Credential Changes
Better ownership identification, Smart Charging Preferences support, case-insensitive fields, and multi-role credential support.
Transport & Format Changes
New routing headers for Hub communication and required unique message IDs and correlation IDs in every request/response.
Impact Table
| Context | Expected Impact | Expected Effort | Description |
|---|---|---|---|
| CDRs / CDR Object | Medium / Major | Average / Large | Added county_code and party_id fields, making it easier to determine the owner of a CDR.
Added session_id field, making it easier to match a CDR to a Session.
Renamed stop_date_time field to end_date_time, to bring the naming inline with the rest of OCPI.
Changed total_cost field from type: number to Price, this provides the eMSP with the total cost including VAT.
Replaced auth_id field with CdrToken. auth_id alone could not be used to uniquely identify a Token. By copying the information for the dynamic Token object, the CDR will always reflect the 'true' status of Token at the start of the charging session.
Replaced location field with cdr_location, this also changed type, from Location to CdrLocation. Reusing the Location Object always caused a lot of confusing, things were not clear. By creating a dedicated object CdrLocation with only the relevant fields, things should be much clearer.
Added credit and credit_reference_id fields, to allow for Credit CDRs to be send.
Added total_fixed_cost, total_energy_cost, total_time_cost, total_parking_cost and total_reservation_cost fields, to allow more cost details in the CDRs.
Added authorization_reference field for binding an authorization to the resulting session.
Added signed_data field, enabling OCPI to be used to transport signed meter data from the Charge Point to the eMSP and EV driver, can be used for Eichrecht.
Added invoice_reference_id field (optional), to allow a CDRs to reference an invoice.
Field id changed in length from 36 to 39, to allow for something to be appended after the original id in case of a Credit CDR. |
| Commands / AuthMethod enum | Minor / Minor | Minimal / Minimal | Added COMMAND value, to enable reporting authorization via Command like: StartSession or ReserveNow. |
| CDRs / CdrDimensionType enum | Medium / Medium | Minimal / Minimal | Added RESERVATION_TIME value, to enable reporting of cost for a reservation in a Session or CDR. |
| CDRs / CdrDimensionType enum | Medium / Medium | Minimal / Minimal | Removed FLAT value, that is of no use on a CDR, only causes confusion, should have been removed when CdrDimensionType was created from DimensionType of OCPI 2.0. |
| CDRs / ChargingPeriod class | Medium / Medium | Minimal / Minimal | Added tariff_id field to ChargingPeriod, when the session switches from one tariff to another, this needs to be known, can be relevant with Preference based Smart Charging. |
| ChargingProfiles | Major / Major | Large / Large | Added new ChargingProfiles module. |
| Commands / CancelReservation Object | Minor / Minor | Minimal / Minimal | Added CancelReservation object for the cancel reservation command. |
| Commands / CommandType Enum | Minor / Minor | Minimal / Minimal | Added CANCEL_RESERVATION value, adding the cancel reservation command. |
| Commands / CommandResponse Object | Minor / Minor | Minimal / Minimal | Added message field, enables the CPO to send a message to the user when something goes wrong.
Added timeout field, enables the eMSP to cleanup not responded outstanding commands. |
| Commands / ReserveNow Object | Minor / Medium | Minimal / Average | Changed location_id and evse_uids from string to CiString, making them case-insensitive, which had always been the idea. Lengths changed from 39 to 36, matching changes in the object definitions.
Changed reservation_id from int to CiString(36), making it possible to use UUIDs.
Added authorization_reference field for binding an authorization to the resulting session.
Changed/added requirements in description of ReserveNow Object. |
| Commands / StartSession Object | Minor / Medium | Minimal / Average | Changed location_id and evse_uids from string to CiString, making them case-insensitive, which had always been the idea. Lengths changed from 39 to 36, matching changes in the object definitions.
Added authorization_reference field for binding an authorization to the resulting session.
Changed/added requirements in description of StartSession Object. |
| Commands / StopSession Object | Minor / Minor | Minimal / Minimal | Changed session_id from string to CiString, making it case-insensitive, which had always been the idea. |
| Commands / UnlockConnector Object | Minor / Minor | Minimal / Minimal | Changed location_id, evse_uids and connector_ids from string to CiString, making them case-insensitive, which had always been the idea. Length of location_id and evse_uids changed from 39 to 36, matching changes in the object definitions.
Removed connector_ids, this was not usable as they are not unique within the Location, there is also no use case. |
| Commands / CommandResponseType Enum | Minor / Minor | Minimal / Minimal | Removed TIMEOUT as possible value. This is moved to the new CommandResult object. |
| Commands / CommandResultType Enum | Minor / Minor | Minimal / Minimal | Added CANCELED_RESERVATION value. Make it possible for a CPO to cancel an existing reservation in case of issues with the Charge Point. |
| Commands / CommandResult Object | Medium / Medium | Medium / Medium | Changed result message from CPO to eMSP from CommandResponse to CommandResult to make it more clear. |
| Credentials / Credentials Object | Minor / Minor | Minimal / Minimal | Changed country_code and party_id from string to CiString, making them case-insensitive, which had always been the idea.
Replaced the business_details, party_id and country_code field with a roles list. Making it possible to implement different parties and roles in the same OCPI instance. The fields are now moved into a new CredentialsRole class. |
| HubClientInfo | Medium / Medium | Medium / Medium | Added new HubClientInfo module. |
| Locations / Sender GET Object method | Minor / Minor | Minimal / Minimal | Changed location_id, evse_uids and connector_ids from string to CiString, making them case-insensitive, which had always been the idea. Length of location_id and evse_uids changed from 39 to 36, matching changes in the object definitions. |
| Locations / Receiver GET & PUT methods | Minor / Minor | Minimal / Minimal | Changed country_code, party_id, location_id, evse_uids and connector_ids from string to CiString, making them case-insensitive, which had always been the idea. Length of location_id and evse_uids changed from 39 to 36, matching changes in the object definitions. |
| Locations / Receiver PATCH method | Minor / Minor | Minimal / Minimal | Changed country_code, party_id, location_id, evse_uids and connector_ids from string to CiString, making them case-insensitive, which had always been the idea. Length of location_id and evse_uids changed from 39 to 36, matching changes in the object definitions.
Added description on how to handle last_updated, and made it required for all PATCH requests. |
| Locations / Connector Object | Minor / Minor | Minimal / Minimal | Field id is changed from string to CiString, making it now case-insensitive, which had always been the idea.
Added max_electric_power field, some DC Fast Charger have a lower max power then can be calculated from voltage and amperage.
Changed tariff_id field to tariff_ids, and changed cardinality from ? to *. Making it possible to make provided tariffs for different Smart Charging Preferences and also for ad hoc payment. Changed type from string to CiString, matching the change to Tariff.id.
Changed amperage field to max_amperage and voltage field to max_voltage, to better reflect the real meaning of both fields. |
| Locations / EVSE Object | Minor / Minor | Minimal / Minimal | Fields uid and evse_id is changed from string to CiString, making them case-insensitive, which had always been the idea. Length of uid changed from 39 to 36, as 36 is enough to store UUID and GUIDs. |
| Locations / Location Object | Minor / Minor | Minimal / Minimal | Added county_code and party_id fields, making it easier to determine the owner of a Location.
Field id is changed from string to CiString, making it now case-insensitive, which had always been the idea. Length changed from 39 to 36, as 36 is enough to store UUID and GUIDs.
Added state field, optional, to allow as much different address schemes from around the world as possible.
Changed postal_code field from required to optional, with the remark that omitting is only allowed when location has no postal_code.
Changed time_zone field from optional to required, as the opening hours and tariff start/end depend on this, they are more and more important.
Renamed type field to parking_type and made it optional. It better reflects what this field really describes.
Added publish field, required, to control which locations may or may not be publish in apps etc.
Added publish_allowed_to field, optional, to give access to locations to only a limited set of users. |
| Locations / AdditionalGeoLocation class | Minor / Minor | Minimal / Minimal | Changed regex for fields: latitude and longitude from fixed 6 decimal places, to more flexible 5 to 7 decimal places. |
| Locations / Capability enum | Minor / Minor | Minimal / Minimal | Added new values for: CHARGING_PREFERENCES_CAPABLE, DEBIT_CARD_PAYABLE and TOKEN_GROUP_CAPABLE. |
| Locations / ConnectorType enum | Minor / Minor | Minimal / Minimal | Added new values for: PANTOGRAPH_TOP_DOWN and PANTOGRAPH_BOTTOM_UP. |
| Locations / EnvironmentalImpact class | Minor / Minor | Minimal / Minimal | Changed field name from source to category, this was a copy/paste error in an older version of OCPI, as this is not used (much) yet, it is better for understandability of OCPI to correct the field name. |
| Locations / Facility enum | Minor / Minor | Minimal / Minimal | Added new values for: BIKE_SHARING, PARKING_LOT, TRAM_STOP and METRO_STATION. |
| Locations / GeoLocation class | Minor / Minor | Minimal / Minimal | Changed regex for fields: latitude and longitude from fixed 6 decimal places, to more flexible 5 to 7 decimal places. |
| Locations / Hours class | Minor / Minor | Minimal / Minimal | Removed the option for either: twentyfourseven or regular_hours, now twentyfourseven is always required and regular_hours is required when twentyfourseven=false, this is much less confusing. |
| Locations / Image class | Minor / Minor | Minimal / Minimal | Changed field type from string to CiString, is for machine to machine communication, so UTF-8 is not needed. |
| Locations / RegularHours class | Minor / Minor | Minimal / Minimal | Improved the regex for time format. |
| Locations / LocationType enum | Minor / Minor | Minimal / Minimal | Renamed to: ParkingType.
Added the values: ON_DRIVEWAY and ALONG_MOTORWAY.
Removed the values: OTHER and UNKNOWN, no longer needed as this is now optional. |
| Sessions / Sender PUT method | Medium / Medium | Large / Large | Added setting Charging Preferences on a session. Providing the CPO with preferences from the driver, needed for Smart Charging. For this the following data types are added: ChargingPreferences, ChargingPreferencesResponse, ProfileType. |
| Sessions / Receiver GET and PUT methods | Minor / Minor | Minimal / Minimal | Changed country_code, party_id and session_id from string to CiString, making them case-insensitive, which had always been the idea. |
| Sessions / Receiver PATCH method | Minor / Minor | Minimal / Minimal | Changed country_code, party_id and session_id from string to CiString, making them case-insensitive, which had always been the idea.
Added description and requirements how to add charging_periods and made last_updated required for all PATCH requests. |
| Sessions / Session Object | Minor / Medium | Minimal / Average | Added county_code and party_id fields, making it easier to determine the owner of a Session.
Field id is changed from string to CiString, making it now case-insensitive, which had always been the idea.
Changed total_cost field from type: number to Price, this provides the eMSP with the total cost including VAT.
Added start_date_time and end_date_time fields.
Replaced auth_id with CdrToken class. auth_id alone could not be used to uniquely identify a Token.
Replaced location object with location_id, evse_uid and connector_id. Having the Location Object in the Session was overkill, only reference is more inline with the rest.
Added authorization_reference field for binding an authorization to the resulting session. |
| Tariffs / Receiver PATCH method | Minor / Minor | Minimal / Minimal | PATCH is removed from Tariffs as this was seen as not useful, use PUT instead. |
| Tariffs / Tariff Object | Minor / Minor | Minimal / Minimal | Added county_code and party_id fields, making it easier to determine the owner of a Tariff.
Field id is changed from string to CiString, making it now case-insensitive, which had always been the idea.
Renamed start_datetime field to start_date_time, to bring the naming inline with the rest of OCPI.
Renamed end_datetime field to end_date_time, to bring the naming inline with the rest of OCPI.
Added optional min_price field, making it possible to set a minimum price on a Charging Session.
Added optional max_price field, making it possible to set a maximum price on a Charging Session.
Added type field to make it possible to make different tariffs for different Smart Charging Preferences and also for ad hoc payment. |
| Tariffs / PriceComponent class | Minor / Minor | Minimal / Minimal | Added vat field to send the applicable VAT with every tariff component. |
| Tariffs / ReservationRestrictionType enum | Minor / Minor | Minimal / Minimal | Added new enum for Reservation restrictions. |
| Tariffs / TariffRestrictions class | Minor / Minor | Minimal / Minimal | Added optional reservation field, making it possible to define the tariff of a reservation (and an expired reservation).
Added optional min_current and max_current field, making it possible to have a tariff that depends on the current being charged, instead of the power.
Improved the regex for time format. |
| Tokens / Sender GET & POST methods | Minor / Minor | Minimal / Minimal | Changed country_code, party_id and token_uid from string to CiString, making them case-insensitive, which had always been the idea. |
| Tokens / Receiver GET & PUT methods | Minor / Minor | Minimal / Minimal | Changed country_code, party_id and tariff_id from string to CiString, making them case-insensitive, which had always been the idea.
Added token_type field, making it possible to make a distinction between different Token types with the same uid. |
| Tokens / Receiver PATCH method | Minor / Minor | Minimal / Minimal | Changed country_code, party_id and tariff_id from string to CiString, making them case-insensitive, which had always been the idea.
Added token_type field, making it possible to make a distinction between different Token types with the same uid.
Made last_updated required for all PATCH requests. |
| Tokens / Token Object | Minor / Minor | Minimal / Minimal | Added county_code and party_id fields, making it easier to determine the owner of a Token.
Fields uid changed from string to CiString, making it now case-insensitive, which had always been the idea.
Fields auth_id renamed to contract_id, a much more logical and less confusing name. Also changed from string to CiString, making it now case-insensitive, which had always been the idea.
Added group_id field to enable support for OCPP GroupId/ParentId.
Added default_profile_type field to enable a default Preference base Smart Charging ProfileType to be provided for a user.
Added energy_contract field to make it possible, if allowed, to use a drivers energy supplier/contract at a Charge Point. |
| Tokens / AuthorizationInfo Object | Minor / Medium | Minimal / Average | Added token field to enable real-time authorization of unknown Tokens.
Added authorization_reference field for binding an authorization to the resulting session. |
| Tokens / LocationReferences class | Minor / Minor | Minimal / Minimal | Changed location_id and evse_uids from string to CiString, making them case-insensitive, which had always been the idea. Length of location_id and evse_uids changed from 39 to 36, matching changes in the object definitions.
Removed connector_ids, this was not usable as they are not unique within the Location, there is also no use case. |
| Tokens / TokenType enum | Minor / Minor | Minimal / Minimal | Added value AD_HOC_USER and APP_USER. As more and more eMSPs are launching Apps, this becomes more common, so special categories are useful. |
| Versions / Endpoint class | Medium / Medium | Minimal / Minimal | Field role added, making it possible to have one OCPI version end-point for both eMSP and CPO role, so one OCPI connection when both CPO and eMSP implemented by the same party. |
| Transport & Format | Medium / Medium | Medium / Medium | To enable routing of messages through a Hub, new OCPI-to- and OCPI-from- headers are introduced. |
| Transport & Format | Minor / Minor | Minimal / Minimal | Unique message ID and Correlation message ID headers are now required in every request/response. |
| Types / DateTime | Minor / Minor | Minimum / Minimum | Changed to: RFC 3339 (was ISO 8601) this does not change the OCPI format, RFC 3339 is more limited, and therefore more inline with OCPI than ISO 8601 was. Fractional seconds are now allowed. |
| Types / string | Minor / Minor | Minimum / Minimum | Type string changed from ASCII to UTF-8. String is used for human-readable information and thus needed to support for a lot more character sets than only ASCII. |