OCPI 2.3.0: remaining normative conformance gaps in OpenEnum, DateTime, role bundles, and metadata

[juherr]

Version

• OpenAPI 2.1.1
• OpenAPI 2.2.1
• OpenAPI 2.3.0
• Migration Guide 2.1.1 → 2.2.1
• Migration Guide 2.1.1 → 2.3.0
• Migration Guide 2.2.1 → 2.3.0

Summary

An audit of the OCPI 2.3.0 OpenAPI against the normative
release-2.3.0-bugfixes documentation found several remaining conformance
gaps that are not covered by the existing issues.

References used for this report:

• OpenAPI: commit 7bacd82ba531fc565fc6d7a09a49d4dabd3aaef0
• Normative OCPI documentation: commit 9ed1e39c24f5b84cb1e4008939f47bea838f9b25

1. OpenEnum schemas are semantically closed

OCPI 2.3.0 introduces OpenEnum for values whose known set is not exhaustive.
Implementations are allowed to send additional string values.

Normative definition:

https://github.com/ocpi/ocpi/blob/release-2.3.0-bugfixes/types.asciidoc#openenum-type

The OpenAPI currently models these schemas as:

type: string
format: open-enum
enum:
  - KNOWN_VALUE

For example:

openapi-specification/ocpi/2.3.0/modules/locations/schema.yaml

Lines 868 to 885 in 7bacd82

	Capability:
	type: string
	format: open-enum
	description: The capabilities of an EVSE.
	enum:
	- CHARGING_PROFILE_CAPABLE
	- CHARGING_PREFERENCES_CAPABLE
	- CHIP_CARD_SUPPORT
	- CONTACTLESS_CARD_SUPPORT
	- CREDIT_CARD_PAYABLE
	- DEBIT_CARD_PAYABLE
	- PED_TERMINAL
	- REMOTE_START_STOP_CAPABLE
	- RESERVABLE
	- RFID_READER
	- START_SESSION_CONNECTOR_REQUIRED
	- TOKEN_GROUP_CAPABLE
	- UNLOCK_CAPABLE

format: open-enum is not a standard OpenAPI/JSON Schema format and does not
change the semantics of enum. Standard validators and generated clients will
therefore reject values that are valid according to OCPI.

Affected schemas include at least:

• Capability
• ConnectorCapability
• ConnectorType
• EnvironmentalImpactCategory
• Facility
• ImageCategory
• ModuleID
• ParkingRestriction
• ParkingType
• TokenType
• VehicleType
• VersionNumber
• CommandType

Suggested fix

Represent known values as documentation while keeping validation open, for
example:

anyOf:
  - type: string
    enum:
      - KNOWN_VALUE
  - type: string

Alternatively, keep type: string unrestricted and expose known values through
a vendor extension supported by the documentation and code-generation tools.

format: open-enum and x-enumDescriptions may remain as non-normative
documentation extensions.

Commands-specific consequence

The Commands Receiver interface currently exposes only five literal paths:

• /commands/CANCEL_RESERVATION
• /commands/RESERVE_NOW
• /commands/START_SESSION
• /commands/STOP_SESSION
• /commands/UNLOCK_CONNECTOR

This prevents an extension command represented by the normative open
CommandType from being described or called by a generated client.

Consider exposing /commands/{command} with an open CommandType path
parameter, while retaining the known command payload schemas.

2. format: date-time does not encode the OCPI DateTime restrictions

The normative OCPI DateTime differs from generic RFC 3339:

• timestamps SHALL be in UTC;
• +00:00 is explicitly not equivalent to UTC for OCPI;
• the Z designator may be omitted;
• fractional seconds may be used;
• the value is limited to string(25).

Normative definition:

https://github.com/ocpi/ocpi/blob/release-2.3.0-bugfixes/types.asciidoc#datetime-type

The OpenAPI currently uses only:

type: string
format: date-time

Examples occur in the common response schemas and throughout the module
schemas.

This has two interoperability effects:

1. Generic validators accept offsets such as +00:00, which OCPI forbids.
2. Some validators reject timestamps without a timezone designator, which OCPI
   explicitly permits.

Suggested fix

Introduce a reusable OCPI DateTime schema with:

• type: string
• maxLength: 25
• a pattern matching the OCPI UTC forms with optional fractional seconds and
  optional Z

Use the same schema for object properties and for the date_from and date_to
query parameters.

3. Generated role bundles omit the Payments module

config.json declares the Payments module:

openapi-specification/ocpi/2.3.0/config.json

Lines 43 to 47 in 7bacd82

	"payments": {
	"label": "Payments",
	"description": "Payment terminals and financial advice confirmations.",
	"interfaces": ["sender-interface", "receiver-interface"]
	},

However, the role configuration does not include either Payments interface:

openapi-specification/ocpi/2.3.0/config.json

Lines 64 to 90 in 7bacd82

	"roles": {
	"cpo": [
	"credentials/interface",
	"versions/interface",
	"locations/sender-interface",
	"sessions/sender-interface",
	"cdrs/sender-interface",
	"tariffs/sender-interface",
	"tokens/receiver-interface",
	"commands/receiver-interface",
	"chargingprofiles/receiver-interface"
	],
	"msp": [
	"credentials/interface",
	"versions/interface",
	"locations/receiver-interface",
	"sessions/receiver-interface",
	"cdrs/receiver-interface",
	"tariffs/receiver-interface",
	"tokens/sender-interface",
	"commands/sender-interface",
	"chargingprofiles/sender-interface"
	],
	"hub": [
	"hubclientinfo/sender-interface"
	]
	}

The build script generates role documentation exclusively from these arrays.
Consequently:

• the CPO role bundle omits payments/receiver-interface;
• no PTP role bundle exposes payments/sender-interface.

Payments is explicitly introduced by the OCPI 2.3.0 changelog and has a
normative module chapter.

Suggested fix

• Add payments/receiver-interface to the CPO role.
• Add a PTP role containing payments/sender-interface, or document why the
  role bundles intentionally exclude the PTP role.

The separate mismatch between ModuleID, Bookings, Payments, and the normative
documentation is already tracked by #9.

4. Two OCPI 2.3.0 interfaces declare info.version: 2.2.1

The following files have a 2.3.0 title and documentation link but declare
version 2.2.1:

• Commands Sender:
  

  openapi-specification/ocpi/2.3.0/modules/commands/sender-interface.yaml

  Lines 1 to 19 in 7bacd82

  	openapi: 3.1.0
  	info:
  	title: OCPI 2.3.0 - Commands Module - Sender Interface
  	description: |
  	The Sender Interface is typically implemented by market roles like the eMSP.
  	It receives the asynchronous responses from the Charge Point via the CPO.
  	The URL structure is open for the Sender to define. The URL is provided to the Receiver
  	by the Sender in the POST to the Receiver interface via the response_url field.
  	Therefore OCPI does not define fixed URL variables.
  	The path shown here is a typical implementation pattern.
  	version: 2.2.1
  	contact:
  	name: EVRoaming Foundation
  	url: https://evroaming.org
  	externalDocs:
  	description: OCPI 2.3.0 Specification
  	url: https://github.com/ocpi/ocpi/blob/master/mod_commands.asciidoc

• ChargingProfiles Sender:
  

  openapi-specification/ocpi/2.3.0/modules/chargingprofiles/sender-interface.yaml

  Lines 1 to 19 in 7bacd82

  	openapi: 3.1.0
  	info:
  	title: OCPI 2.3.0 - ChargingProfiles Module - Sender Interface
  	description: |
  	The Sender Interface is typically implemented by market roles like the eMSP or SCSP.
  	It receives the asynchronous responses from the Charge Point via the CPO,
  	and updated ActiveChargingProfiles when the CPO knows the profile has changed.
  	For the POST method: The URL structure is open for the Sender to define. The URL is provided
  	to the Receiver via the response_url field. The path shown here is a typical implementation pattern.
  	For the PUT method: The endpoint structure is {chargingprofiles_endpoint_url}/{session_id}.
  	version: 2.2.1
  	contact:
  	name: EVRoaming Foundation
  	url: https://evroaming.org
  	externalDocs:
  	description: OCPI 2.3.0 Specification
  	url: https://github.com/ocpi/ocpi/blob/master/mod_charging_profiles.asciidoc

Suggested fix

Set info.version to 2.3.0 in both files.

5. Version-specific externalDocs links point to mutable or invalid targets

Most 2.3.0 interfaces link to files under ocpi/ocpi/blob/master, rather than
the release-2.3.0-bugfixes branch.

There are also invalid targets, for example the Payments interfaces reference
mod_payment.asciidoc, while the normative filename is
mod_payments.asciidoc.

Suggested fix

Point 2.3.0 externalDocs links to the corresponding files under:

https://github.com/ocpi/ocpi/blob/release-2.3.0-bugfixes/

and correct stale filenames.

Existing related issues

The following findings are intentionally not duplicated here:

• Extra CdrDimensionType values: OCPI 2.3.0: CdrDimensionType #12
• Bookings/Payments mismatch with the normative module list: OCPI 2.3.0: bookings and payments module missing in original docs #9
• Tariffs and BookingRestrictionType: Tariffs 2.3.0 #16
• Version endpoint paths being implementation-defined: Versions 2.2.1 & 2.3.0 endpoints #13
• ChargingProfiles Sender callback URL structure: ChargingProfiles 2.3.0 #24

Proposed completion criteria

• OpenEnum schemas accept unknown string values.
• Custom CommandType values can be represented.
• DateTime validation follows the OCPI-specific UTC rules.
• Payments appears in the appropriate generated role bundles.
• All 2.3.0 interface metadata reports version 2.3.0.
• Version-specific documentation links resolve to the normative 2.3.0 branch.

[juherr]

Follow-up audit against OCPI 2.3.0 Edition 2

The normative reference used in the original report has since been superseded by OCPI 2.3.0 Edition 2.

Updated references:

• OCPI core Edition 2: v2.3.0-ed2, commit 32a74ae78daac5ab257ddf502c6b04a817902722
• OCPI Edition 2 with Payments: v2.3.0-ed2-payments, commit 774e23a925c158481cd8cc9f8fc6824c1b11eaae
• OpenAPI audited in the original report: commit 7bacd82ba531fc565fc6d7a09a49d4dabd3aaef0

The following conclusions from the original issue remain valid:

1. OpenEnum schemas remain semantically closed.
   Edition 2 does not change the OpenEnum semantics. Unknown string values permitted by OCPI would still be rejected by standard validators when represented with a regular OpenAPI enum.

2. The Commands interface still needs to support extension commands.
   CommandType remains an OpenEnum, so exposing only the five standard literal paths does not fully represent the normative extension mechanism.

3. The DateTime mismatch remains.
   Edition 2 does not change the OCPI-specific DateTime restrictions. A generic format: date-time still accepts forms forbidden by OCPI and may reject forms permitted by OCPI.

4. The incorrect info.version: 2.2.1 values remain errors.
   They should be changed to 2.3.0. Edition 2 is an edition of the same protocol version, so 2.3.0-ed2 should not be used as the OCPI protocol version.

5. Mutable or broken externalDocs links remain a problem.
   However, release-2.3.0-bugfixes is no longer the appropriate target. Core links should now target v2.3.0-ed2, while Payments-specific links should target v2.3.0-ed2-payments.

Payments role bundles

The original Payments conclusion needs to be qualified.

Edition 2 now publishes the core and Payments specifications separately:

• the core Edition 2 specification contains Invoice Reconciliation and does not contain Payments;
• the Edition 2 Payments specification additionally contains the Payments module.

Therefore, Payments should not simply be added to the core role bundles. The generated OpenAPI descriptions should distinguish between:

• core Edition 2 bundles, which exclude Payments;
• Edition 2 Payments bundles, which expose the Payments Receiver interface for CPOs and the Sender interface for PTPs.

The current OpenAPI still mixes Payments into its general 2.3.0 module configuration without generating the corresponding role bundles, so the technical inconsistency remains, but its resolution should now be edition-specific.

New Edition 2 gaps

Edition 2 adds the standard invoicereconciliation module, but it is absent from the current OpenAPI description.

The OpenAPI should add:

• the Invoice Reconciliation Sender interface;
• the Invoice Reconciliation Receiver interface;
• the InvoiceReconciliationRecord schema;
• invoicereconciliation as a known standard value of the open ModuleID;
• the module to the appropriate CPO and MSP role bundles.

The normative Edition 2 documentation itself appears to contain a related inconsistency: mod_invoice_reconciliation.asciidoc declares invoicereconciliation as the module identifier, but the ModuleID table in version_information_endpoint.asciidoc does not list it.

Edition 2 also introduces schema changes not represented by the current OpenAPI:

• SignedValue.plain_data has a maximum length of 5000, rather than 512;
• Location.address has a maximum length of 255, rather than 45;
• Location.state has a maximum length of 45, rather than 20;
• CdrDimensionType.PARKING_TIME now means time during which the vehicle is not requesting power, rather than merely time during which it is not charging.

The changed Location lengths apply to the Location object. They do not change the existing lengths of the corresponding CdrLocation fields.

Finally, the Edition 2 correction concerning HTTP 401/403 responses does not define a new mandatory 403 response. Existing 401 responses remain appropriate where required by the Authorization header rules.