Types
1. Types
1.1. class
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.
In the serialized JSON form of OCPI messages, class values are serialized as JSON objects.
1.2. enum
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.
In the serialized JSON form of OCPI messages, enum values are serialized as JSON strings.
1.3. OpenEnum type
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.
In the serialized JSON form of OCPI messages, OpenEnum values are serialized as JSON strings.
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 https://evroaming.org/extending-ocpi/.
1.4. CiString type
Case Insensitive String. Only printable ASCII allowed. (Non-printable characters like: Carriage returns, Tabs, Line breaks, etc are not allowed)
1.5. DateTime type
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.
Example of how timestamps shall be formatted in OCPI, other formats/patterns are not allowed:
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| +00:00 is not the same as UTC. |
1.6. DisplayText class
| Property | Type | Card. | Description |
|---|---|---|---|
language |
string(2) |
1 |
Language Code ISO 639-1. |
text |
string(512) |
1 |
Text to be displayed to a end user. No markup, html etc. allowed. |
Example:
{
"language": "en",
"text": "Standard Tariff"
}1.7. number type
Numbers in OCPI are formatted as JSON numbers. Unless mentioned otherwise, numbers use 4 decimals and a sufficiently large amount of digits.
1.8. Price class
| Property | Type | Card. | Description |
|---|---|---|---|
before_taxes |
1 |
Price/Cost excluding taxes. |
|
taxes |
* |
All taxes that are applicable to this price and relevant to the receiver of the Session or CDR. |
1.9. TaxAmount class
| Property | Type | Card. | Description |
|---|---|---|---|
name |
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 |
? |
Tax Account Number of the business entity remitting these taxes. Optional as this is not required in all countries. |
|
percentage |
? |
Tax percentage. Optional as this is not required in all countries. |
|
amount |
1 |
The amount of money of this tax that is due. |
1.10. Role enum
| 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. |
1.11. string type
Case Sensitive String. Only printable UTF-8 allowed. (Non-printable characters like: Carriage returns, Tabs, Line breaks, etc are not allowed)
All strings in messages and enumerations are case sensitive, unless explicitly stated otherwise.
1.12. URL type
An URL a string(255) type following the w3.org spec.