Breaking Changes Definition

This document defines what constitutes a breaking change versus a non-breaking change for the components of the EVerest public API. Understanding these definitions is critical for both maintainers and integrators. For details on how planned breaking changes are managed through the deprecation process, see Deprecation Policy for EVerest.

Overview

General Principle

A change is considered breaking if it requires integrators to modify their code, configuration, or deployment to maintain existing functionality. A change is non-breaking if existing integrations continue to work without modification when upgrading to a new version of EVerest.

Scope

This document covers breaking change definitions for all components of the EVerest public API.

This includes:

Public API components that are explicitly marked as experimental are exempt from these definitions: changing or removing an experimental component is not considered a breaking change. See Experimental Components.

AsyncAPI Changes

Breaking Changes

The following changes to AsyncAPI specifications are considered breaking:

Channels:

  • Changing a channel address (e.g., e2m/session_event → e2m/session_events)

  • Removing a channel that external clients use

Operations:

  • Removing an operation (send/receive) that external clients use

  • Changing an operation’s action (e.g., send → receive)

  • Changing which channel an operation references

Messages:

  • Removing a field from a message payload that clients may read

  • Changing the data type of an existing field (e.g., number → string)

  • Making an optional field required in messages that clients send

  • Changing field semantics that affect expected behavior (e.g., units, value ranges)

  • Adding required constraints to previously unconstrained fields

  • Changing enum values or removing enum options

Behavioral Changes:

  • Changing error handling behavior (e.g., silently ignoring invalid values → raising errors)

  • Changing validation strictness (e.g., accepting malformed data → rejecting it)

  • Changing message ordering or timing guarantees that clients depend on

Protocol:

  • Removing support for a protocol version that clients use

  • Changing server host, pathname, or protocol bindings

Examples

Breaking: Renaming channel e2m/session_event → e2m/session_events breaks all subscribers.

Breaking: Changing EVInfo.soc from number to string requires client parser updates.

Breaking: Making StopTransactionRequest.id_tag required breaks clients that omit it.

Breaking: Requiring m2e/disable_charging to be called before m2e/unlock_connector breaks clients that previously called unlock directly.

Breaking: Previously accepting invalid connector_id: -1 and ignoring it, now rejecting with error breaks clients sending invalid data.

Non-Breaking Changes

The following changes are generally non-breaking:

Channels:

  • Adding a new channel with a new address

Operations:

  • Adding a new operation on a new or existing channel

Messages:

  • Adding a new message type (clients can ignore unknown messages)

  • Adding optional fields to existing message payloads

  • Making a required field optional in messages that EVerest sends

  • Adding new enum values

  • Expanding valid value ranges (e.g., minimum: 0 → minimum: -10)

Documentation:

  • Clarifying documentation without changing behavior

  • Adding examples or improving descriptions

Protocol:

  • Adding a new protocol version while maintaining existing versions

Examples

Non-breaking: Adding new channel e2m/detailed_session_event alongside existing e2m/session_event.

Non-breaking: Adding optional field battery_temperature to EVInfo (clients can ignore).

Non-breaking: Adding "FastCharging" to SessionEventEnum (if clients handle unknown values).

Configuration, Storage, and Module Contracts

Configuration changes directly affect deployment processes and runtime behavior. The following principles apply to EVerest YAML/SQLite configurations and OCPP JSON/SQLite configurations.

Some SQLite implementations in EVerest support automatic schema migrations to minimize breaking changes. However, schema changes requiring manual intervention or altering existing data formats are considered breaking.

This contract also covers the availability of the EVerest modules that a configuration references by name. Only a module’s availability under a stable name is guaranteed: its implementation may be replaced as long as the replacement keeps providing equivalent functionality. The interfaces and types it provides are internal and may change without notice.

Breaking Changes

Configuration Options:

  • Removing a configuration option that deployments use

  • Renaming a configuration option (e.g., connector_type → connector_standard)

  • Changing the type of a value (e.g., boolean → string)

  • Making an optional option required without a sensible default

  • Changing the meaning or behavior of an option (e.g., units, semantics)

  • Changing default values that affect runtime behavior

  • Narrowing acceptable value ranges (e.g., 0-100 → 1-100)

Modules:

  • Removing a module name that a configuration may reference, without providing a replacement of equivalent functionality under the same name

  • Renaming a module so that the original name is no longer available

File Formats:

  • Changing YAML/JSON schema in incompatible ways (e.g., structure changes)

  • Changing file locations or naming conventions that deployments rely on

Database Schemas:

  • Removing or renaming tables/columns that are actively used

  • Changing column types without migration support

  • Adding NOT NULL constraints to existing columns without defaults

  • Changing primary keys or foreign key relationships

Examples

Breaking: Removing EvseManager.connector_id breaks all configs that set it.

Breaking: Changing ac_hlc_enabled from boolean to enum ("always"|"never") breaks existing configs.

Breaking: OCPP: Renaming table VARIABLE_ATTRIBUTE → VARIABLE_ATTRIBUTES without migration.

Breaking: Removing the OCPP module without a same-name replacement breaks every configuration that instantiates it.

Non-Breaking Changes

Configuration Options:

  • Adding a new optional option with a documented default

  • Making a required option optional with a backward-compatible default

  • Expanding acceptable value ranges if existing implementations don’t reject the new values (e.g., 1-100 → 0-100)

  • Adding new enum values while preserving existing ones

  • Improving documentation or examples

Modules:

  • Replacing a module’s implementation while keeping the same module name and equivalent functionality (e.g., introducing an improved module under the existing name and retiring the previous implementation under a different name)

Database Schemas:

  • Adding a new table for new functionality

  • Adding a new column with a default value and automatic migration

  • Adding optional indexes for performance

  • Relaxing NOT NULL constraints

Examples

Non-breaking: Adding EvseManager.enable_load_balancing with default false.

Non-breaking: Accepting connector_type: "CCS1" alongside existing "CCS".

Non-breaking: OCPP: Adding VARIABLE_ATTRIBUTE.last_updated column with default NULL and migration script.

Non-breaking: Shipping a rewritten EvseManager under the same name with equivalent configuration and behavior, while moving the previous implementation to EvseManagerLegacy.

Practical Guidelines

When in Doubt

If you are unsure whether a change is breaking:

  • Assume it is breaking and treat it conservatively

  • Consult with the maintainers and/or TSC for significant changes

  • Gather community feedback during testing periods

  • Test with real-world deployments when possible

Review Checklist

Before merging changes, ask yourself these questions:

Configuration Compatibility

  1. Can existing EVerest and OCPP configuration files still be loaded?

  2. Will existing configuration values still have the same effect?

  3. Are we changing any default values?

  4. Are we removing or renaming any configuration options?

Integration Compatibility

  1. Will existing external API clients continue to work?

  2. Are we removing or changing any public API methods/messages?

  3. Are we changing any API semantics, expected behaviors, or side effects?

  4. Will existing stored data still be readable?

Behavioral Compatibility

  1. Are we changing behavior that deployments rely on?

  2. Are we removing functionality that might be in use?

  3. Are bug fixes potentially breaking workarounds?

  4. Will performance characteristics change significantly?

Additional Resources

For questions about breaking changes or to report potential compatibility issues, please contact the EVerest maintainers via Zulip.