OCPI 2.3.0 Chapter 18

Types

Fundamental data types used throughout the OCPI 2.3.0 specification. This chapter defines the primitive types (class, enum, OpenEnum, string, number), formatting rules (CiString, DateTime, URL), and common reusable classes (DisplayText, Price, TaxAmount, Role).

12 Sections

OCPI 2.3.0-booking-1.0

2025-06-13

18.1. class

Type Definition

When a data type is defined as a "class" in the OCPI specification, we mean a type whose possible values are sets of zero or more pairs of a string and another value. The string is known as a "key", "field name", or "property", and the value associated with the key is known as a field value. For each class type, the specification lists which strings are required and allowed to occur as field names in values of that type, and what the types of the field values of these fields should be.

Serialization: In the serialized JSON form of OCPI messages, class values are serialized as JSON objects.

18.2. enum

Type Definition

When a data type is defined as an "enum" in the OCPI specification, we mean a type whose possible values are a finite number of strings.

This type is used for class fields where it is clear that there is only a finite set of possible values that is completely known at the time of writing of the specification. An example of a place where this is used is a class field whose possible values are the days of the week.

Serialization: In the serialized JSON form of OCPI messages, enum values are serialized as JSON strings.

18.3. OpenEnum

Type Definition

The OpenEnum type is meant for class fields for which the set of all possible values is not known at the time of writing of the specification, but where there are a finite number of known possible values. In this case we want to specify how OCPI implementers can use the known possible values, but also leave room for them to use other values.

This is used for example for connector types, where all implementers should use the same value to identify a widely used connector type like the Type 2 "Mennekes" plug, but where there should also be room for implementers to name new or custom plug types that were not taken into account by OCPI's authors.

Serialization: In the serialized JSON form of OCPI messages, OpenEnum values are serialized as JSON strings.

Naming Guidelines

Recommendations: When naming new OpenEnum values, OCPI implementers SHOULD follow the "Recommendations for Creators of New Parameters" found in IETF RFC 6648, and SHOULD consult EV Roaming Foundation's guidance on extending OCPI at evroaming.org/extending-ocpi/.

18.4. CiString

Type Definition

Case Insensitive String. Only printable ASCII allowed.

Restriction: Non-printable characters like: Carriage returns, Tabs, Line breaks, etc. are not allowed.

18.5. DateTime

Type Definition

Format Rules

All timestamps are formatted as string(25) following RFC 3339, with some additional limitations.

All timestamps SHALL be in UTC. The absence of the timezone designator implies a UTC timestamp. Fractional seconds MAY be used.

Examples

Examples of how timestamps shall be formatted in OCPI. Other formats/patterns are not allowed:

DateTime Format Examples

2015-06-29T20:39:09Z
2015-06-29T20:39:09
2016-12-29T17:45:09.2Z
2016-12-29T17:45:09.2
2018-01-01T01:08:01.123Z
2018-01-01T01:08:01.123

Note: +00:00 is not the same as UTC.

18.6. DisplayText

Class

Properties

Property	Type	Card.	Description
`language`	string(2)	`1`	Language Code ISO 639-1.
`text`	string(512)	`1`	Text to be displayed to an end user. No markup, HTML etc. allowed.

Example

DisplayText Example

{
  "language": "en",
  "text": "Standard Tariff"
}

18.7. number

Type Definition

Numbers in OCPI are formatted as JSON numbers. Unless mentioned otherwise, numbers use 4 decimals and a sufficiently large amount of digits.

18.8. Price

Class

Properties

Property	Type	Card.	Description
`before_taxes`	number	`1`	Price/Cost excluding taxes.
`taxes`	TaxAmount	`*`	All taxes that are applicable to this price and relevant to the receiver of the Session or CDR.

18.9. TaxAmount

Class

Properties

Property	Type	Card.	Description
`name`	string	`1`	A description of the tax. In countries where a tax name is required like Canada this can be something like "QST". In countries where this is not required, this can be something more generic like "VAT" or "General Sales Tax".
`account_number`	string	`?`	Tax Account Number of the business entity remitting these taxes. Optional as this is not required in all countries.
`percentage`	number	`?`	Tax percentage. Optional as this is not required in all countries.
`amount`	number	`1`	The amount of money of this tax that is due.

18.10. Role

Enum

Values

Value	Description
`CPO`	Charge Point Operator Role.
`EMSP`	eMobility Service Provider Role.
`NAP`	National Access Point Role (national Database with all Location information of a country).
`NSP`	Navigation Service Provider Role, role like an eMSP (probably only interested in Location information).
`OTHER`	Other role.
`SCSP`	Smart Charging Service Provider Role.

18.11. string

Type Definition

Case Sensitive String. Only printable UTF-8 allowed.

Restriction: Non-printable characters like: Carriage returns, Tabs, Line breaks, etc. are not allowed.

Case Sensitivity: All strings in messages and enumerations are case sensitive, unless explicitly stated otherwise.

18.12. URL

Type Definition

An URL is a string(255) type following the w3.org spec.