Processes for Feature Development for OCPI

New products, services and technologies keep appearing at a steady pace. When this happens, it should be possible for OCPI Platforms to refer to these new technologies in data they exchange via OCPI, without needing to upgrade to an incompatible version of OCPI.

An example of this happening in practice would be the appearance of the Megawatt Charging System (MCS) and SAE J-3400 (NACS) connector types. Another imaginable scenario that falls in this category would be the launch of a new on-site payment system besides the existing ones of Visa, MasterCard etc.

Sometimes new capabilities in OCPI are needed because OCPI implementers realize that there is a previously unrecognized use case in the EV charging industry that has to be urgently addressed. Examples of this would be the requirement to provide accessible charging facilities, or the need of heavy-duty fleet operators to book charging times and energy delivery in advance.

It happens that after a version of OCPI is released, the OCPI community realizes that the release fails to support important functionality. In the past, this has led to releases being de facto retracted (like OCPI versions 2.1 and 2.2, and OCPP version 2.0). In other cases, the flaws go unaddressed for years, as happens with OCPI 2.2.1’s failure to support loitering fees with grace periods. If it is possible to add functionality to OCPI without breaking compatibility, such oversights can be dealt with much more swiftly and gently.

It is important for Platforms to know what their partner Platforms support. This allows them to show the right set of controls to their users, and to assign the correct semantics to data that they receive from their partner Platforms.

OCPI, since version 2.3.0, has different types for open and closed enumerations. The type for open enumerations is called OpenEnum; the type for closed enumerations is called enum.

Open enumerations are extension points where new values can be added to adapt to new realities. For example, when a new plug standard appears, a new value can be added to the ConnectorType OpenEnum.

OCPI uses the JSON ([JSON]) data format. JSON is designed for extensibility. Unlike other data exchange formats, JSON allows new fields to be added to message formats without requiring changes to systems that process messages of that format. That means that systems processing JSON messages are typically forward compatible, and new fields can be added easily in JSON-based message formats.

In the EV charging industry however, OCPP has tried to constrain this freedom that JSON provides by providing restrictive JSON Schema files for OCPP that consider OCPP messages invalid when they contain fields not foreseen in the OCPP specification.

With OCPI versions 2.3.0 and 3.0, OCPI is choosing a different direction. We believe that the forward compatibility that JSON encourages can be a great help in easier transitions to new protocol versions.

Adding new fields to JSON messages is a familiar and well-understood way to extend data formats for most developers nowadays. We therefore encourage people looking to extend OCPI to try to do it with just adding JSON fields before considering the more invasive extension points listed below.

OCPI, starting with version 3.0, specifies a generic mechanism for transferring data objects like Locations, Tariffs and CDRs. This generic mechanism is called the Party Issued Object system.

It is possible to extend OCPI by adding new object types that can be transferred using the Party Issued Object system. When adding a new Party Issued Object type, the party adding it must add requirements like those of the "Exchange information" use cases in the OCPI 3.0 specification. These requirements must specify:

OCPI, starting with version 3.0, contains a generic mechanism for making Remote Procedure Calls (RPCs). The generic RPC mechanism is used when a party requests an operation from another party, like starting a charging session on an EVSE or authorizing a charge token for charging.

OCPI users can extend OCPI 3.0 by adding RPC endpoints for operations not previously supported by OCPI. To do so, they must provide requirements like those of the "Operations" use cases in the OCPI 3.0 specification. For each new RPC endpoint, the requirements must state:

It is possible to extend OCPI by adding entirely new data types, complementing those that are defined in the "Fundamental data type definitions" section of the OCPI Functional Use Cases document.

To do so, the extender must provide:

In OCPI versions prior to OCPI 3.0, the Party Issued Object and RPC mechanisms did not exist. Equivalent extensions can be made by describing entirely new HTTP endpoints. When doing so, an extender must describe all properties of these endpoints, including but not necessarily limited to:

Pseudo-invariants are things that are true for many or all current implementations, but that are not in fact invariants of the OCPI protocol. Implementations may encounter OCPI messages or partner Platforms that do not adhere to these statements in the future.

Pseudo-invariants of OCPI 3.0 are:

The principle here is that a middlebox may apply special logic for open enumeration values that it recognizes, but must pass on values that it does not recognize as-is. The following two requirements formalize that.

When a middlebox receives an OpenEnum value that it does not recognize, it MUST pass on the message with this value, and include the value unaltered in forwarded messages to all connected systems to which the data or message containing the value would be forwarded if the value was one that the middlebox recognizes.

When a middlebox receives an OpenEnum value that is not in the base specification but that the middlebox does recognize, it MAY transform the message in a way that makes the message more likely to be acted upon appropriately by the Platform to which the message is forwarded.

OCPI and this whitepaper place no specific requirements on how Hubs and other middleboxes handle fields that are not in the OCPI specification and that they do not recognize.

OCPI and this whitepaper place no specific requirements on how Hubs and other middleboxes handle Party Issued Object types that are not in the OCPI specification and that they do not recognize.

Because of the security risks of forwarding arbitary request verbs to arbitrary URL paths, we recommend OCPI middleboxes to not forward unrecognized Remote Procedure Calls.

When an OCPI Platform receives an HTTP request with a combination of request verb and URL path that it does not recognize, even if the request fits the OCPI specification’s requirements for Remote Procedure Calls, the Platform SHOULD reject these requests with the appropriate HTTP status codes in the 4xx range.

As a middlebox Platform knows the type for all the fields that it recognizes, the middlebox Platform can only encounter extended types that it does not recognize in JSON fields that it also does not recognize.

In such cases, OCPI and this whitepaper [MB: make it "document" or "process", it is much more than a white paper] put no requirements on how the Hub or other middlebox handles the unrecognized datatype in the unrecognized field, as specified under Requirements for middleboxes handling JSON object fields.

Middlebox Platforms SHOULD NOT forward requests to unrecognized endpoints. There are too many degrees of freedom for such requests. Forwarding them would be insecure.

The goal of extensibility, and feature development, is to allow OCPI Platforms that have new capabilities to be interoperable with Platforms that do not have these capabilities. In order to achive that goal, we must acknowledge that extensibility also brings risks for interoperability, and we must put processes in place to make sure that extensibility works for interoperability, not against it.

[MB should change this in: The goal of extensibility, and feature development, is to support new certain new or changed business requirements via OCPI Platforms that have new capabilities AND to be interoperable with Platforms that do not have these capabilities. The EVRoaming Foundation offers the OCPI protocol free to download and use by everyone. That also requires that the Intelectual Property (IP) of the procol and the extensions is at EVRoaming Foundation.

To maintain order and quality when numerous OCPI features are developed in parallel, the EV Roaming Foundation will set up processes and document repositories to develop and disseminate feature documents.

Once a feature document is submitted to the EV Roaming Foundation, the EV Roaming Foundation will assign the feature a number for clear identification. The feature document will then enter into a lifecycle with the following possible stages:

The lifecycle and its stages can be turned into a state diagram as follows:

There are scenarios in which it is the right course of action to make changes to OCPI that are not backward or forward compatible. Examples could be changing the transport from HTTP to another protocol, or changing the data format from JSON to something else.

In many cases, even changes at that level can be done in a backward and forward compatible way, by always starting the connection process in a way that conforms to the existing specification, and only deviating from the existing specification once both platforms have indicated support for the new feature to each other.

In some cases, such a bootstrapping process that conforms to the existing specification may not be possible or worthwhile. When that happens, an incompatible new version of OCPI can be developed. The process described in this paper does not cover that situation. When the OCPI Development Working Group decides that such an incompatible new version is to be developed, the process for doing so must be developed ad hoc, as it was for OCPI 2.x and for OCPI 3.0.

If the feature needs announcement and is supported across all Parties on the Platform, support for the feature SHOULD be announced in an "features" field in the OCPIVersionURL, OcpiConnectionRequest and OcpiConnectionResponse objects sent by the Platform.

The value of this field should be a key-value map, represented as a JSON object. The keys are strings, and each key identifies a supported feature. The values in the map can give extra information required by the receiving Platform to use this feature effectively with the sending Platform. As an example, we could imagine that a future OcpiConnectionRequest with an "features" field could look like this:

This would indicate that the Platform supports a hypothetical feature to send a logo to be displayed on a charger’s screen identified by "send_charging_station_display_logo". It also indicates that the Platform supports a hypothetical feature for encrypting messages between Platforms at the OCPI layer, identified by "message_encryption", and configured with a crypto algorithm and a public key.

If a feature requires explicit announcement at the Platform level, its feature documents SHOULD specify in its "How to detect support in OCPI 3.0" section:

If the feature has to be announced but can be used without exchanging parameters between the Platforms, the value in the key-value map should be specified to be an empty object, that is {}.

If the feature needs announcement and is supported only for certain Parties on the Platform, support for the feature SHOULD be announced in an "features" field in the Party object in the PlatformInformation object.

This field follows the same format, and has the same rules applying to it, as the "features" field described above for features supported across the whole Platform. The only difference is that if an feature is listed in the "features" field in a Party object, that indicates only support for the feature for that specific Party.

From OCPI 3.0 onward, OCPI releases will have version identifiers with two numbers, separated by a dot ('.'). An increment of the first number means a change that breaks backward compatibility. An increment of the second number means that changes were made, but backward compatibility is preserved. That is, Platforms that support different versions that differ only in the second number can connect and interoperate despite interpreting the messages they receive using different versions of the OCPI specification. Platforms that support only different versions that differ in their first number are not interoperable.

This approach is informed by, but not the same as, Semantic Version ([SEMVER]). Semantic Versioning is a specification for versioning software dependencies, and is not applicable to specification documents like OCPI.

If the feature needs announcement and is supported across all Parties on the Platform, support for the feature SHOULD be announced in an "features" field in the response body to the version details endpoint.

The value of this field should be a key-value map, represented as a JSON object. The keys are strings, and each key identifies a supported feature. The values in the map can give extra information required by the receiving Platform to use this feature effectively with the sending Platform. As an example, we could imagine that a future response to a version details endpoint with an "features" field could look like this:

This would indicate that the Platform suports a hypothetical feature to send a logo to be displayed on a charger’s screen identified by "send_charging_station_display_logo". It also indicates that the Platform supports a hypothetical feature for encrypting messages between Platforms at the OCPI layer, identified by "message_encryption", and configured with a crypto algorithm and a public key.

If a feature requires explicit announcement at the Platform level, its feature documents SHOULD specify in its "How to detect support in OCPI 2.3.0" section:

If the feature has to be announced but can be used without exchanging parameters between the Platforms, the value in the key-value map should be specified to be an empty object, that is {}.

If the feature needs announcement and is supported only for certain Parties on the Platform, support for the feature SHOULD be announced in an "features" field in the CredentialsRole object in the Credentials object.

This field follows the same format, and has the same rules applying to it, as the "features" field described above for features supported across the whole Platform. The only difference is that if an feature is listed in the "features" field in a CredentialsRole object, that indicates only support for the feature for that specific Party in that specific role.

In the OCPI 2.x version family, versioning has not been consistent. Platforms SHOULD NOT assume that there is any backward compatibility between different versions in the 2.x family.