Relevant source files

The following files were used as context for generating this wiki page: - [ocpi.cdrs.v221.ts](https://github.com/synergyboat/ocpi-schema/blob/main/ocpi.cdrs.v221.ts) - [ocpi.location.v221.ts](https://github.com/synergyboat/ocpi-schema/blob/main/ocpi.location.v221.ts) - [ocpi.sessions.v221.ts](https://github.com/synergyboat/ocpi-schema/blob/main/ocpi.sessions.v221.ts) - [ocpi.generate.ts](https://github.com/synergyboat/ocpi-schema/blob/main/ocpi.generate.ts) - [ocpi.versions.v221.ts](https://github.com/synergyboat/ocpi-schema/blob/main/ocpi.versions.v221.ts) - [ocpi.tariff.v221.ts](https://github.com/synergyboat/ocpi-schema/blob/main/ocpi.tariff.v221.ts) - [ocpi.credentials.v221.ts](https://github.com/synergyboat/ocpi-schema/blob/main/ocpi.credentials.v221.ts) - [ocpi.tokens.v221.ts](https://github.com/synergyboat/ocpi-schema/blob/main/ocpi.tokens.v221.ts)

# OCPI v2.2.1 Schemas Overview This project provides a comprehensive set of TypeScript-based schemas for the Open Charge Point Interface (OCPI) protocol, specifically version 2.2.1. It utilizes the `zod` library to define strongly-typed data structures for all OCPI modules. These Zod schemas serve as a single source of truth for data validation and type safety within applications that implement OCPI. A key feature of this repository is the automated generation of standard JSON Schemas from the Zod definitions. A script, `ocpi.generate.ts`, processes all the defined Zod objects and outputs corresponding `.json` files into the `.ocpi-schema` directory. This enables developers to use these schemas in any language or environment that supports JSON Schema for validation, documentation, or code generation. Sources: [README.md:1-13](), [ocpi.generate.ts:1-353](), [package.json:4]() ## Schema Generation Process The core of the project is the `ocpi.generate.ts` script, which automates the conversion of Zod schemas to JSON schemas. This process ensures that the JSON schemas are always in sync with the TypeScript type definitions. The workflow is as follows: 1. Zod schemas are defined in `.ts` files, categorized by OCPI module and version (e.g., `ocpi.location.v221.ts`). 2. The `npm run generate.ocpi` command executes the `ocpi.generate.ts` script using `ts-node`. 3. The script imports all Zod schemas and uses the `zod-to-json-schema` library to perform the conversion. 4. The resulting JSON schema files are saved to the `.ocpi-schema` directory, named according to their OCPI version and module (e.g., `ocpi.2_2_1.location.json`). Sources: [ocpi.generate.ts:1-120](), [README.md:9-13]() This diagram illustrates the schema generation flow. ```mermaid flowchart TD A[Zod Schema Definitions
e.g., ocpi.location.v221.ts] --> B{ocpi.generate.ts}; B --> C[zod-to-json-schema library]; C --> D[Generated JSON Schema
e.g., .ocpi-schema/ocpi.2_2_1.location.json]; ``` Sources: [ocpi.generate.ts:117-120]() ## OCPI v2.2.1 Modules & Endpoints The OCPI v2.2.1 specification is divided into several modules, each handling a specific domain. The `ocpi.versions.v221.ts` file defines the available modules and the structure for discovering their endpoints. The `OcpiVersionDetails` object describes the version and a list of `OcpiEndpoint` objects, each containing the module's identifier, its role (SENDER/RECEIVER), and its URL. Sources: [ocpi.versions.v221.ts:30-33]() The available OCPI v2.2.1 modules are defined by the `OcpiModuleId` enum: | Module Identifier | Description | | ------------------- | ------------------------------------------------ | | `cdrs` | Charge Detail Records | | `chargingprofiles` | Smart Charging Profiles | | `commands` | Remote commands (e.g., start/stop session) | | `credentials` | Credentials and role exchange | | `hubclientinfo` | Hub client information | | `locations` | Charge point location information | | `sessions` | Active charging session information | | `tariffs` | Pricing and tariff information | | `tokens` | Authorization tokens | Sources: [ocpi.versions.v221.ts:12-23]() ## Location Module The Location module is fundamental to OCPI, describing the physical locations of charging infrastructure. The schemas are structured hierarchically. This diagram shows the relationship between the main entities in the Location module. ```mermaid erDiagram Location ||--|{ Evse : "contains" Evse ||--|{ Connector : "contains" ``` Sources: [ocpi.location.v221.ts:140](), [ocpi.location.v221.ts:238]() ### Location Schema A `Location` represents a group of one or more EVSEs at a single, addressable place. | Field | Type | Description | | ------------------- | ---------------------------------- | ------------------------------------------------------------------------ | | `id` | `string` (max 36) | Uniquely identifies the location. | | `country_code` | `string` (length 2) | ISO-3166 alpha-2 country code of the CPO. | | `party_id` | `string` (max 3) | CPO ID of the party operating this location. | | `publish` | `boolean` | Indicates if the location is public and can be published. | | `address` | `string` (max 45) | The street address of the location. | | `city` | `string` (max 45) | The city of the location. | | `country` | `string` (length 3) | ISO-3166 alpha-3 country code. | | `coordinates` | `GeoLocation` | The geographical coordinates of the location. | | `evses` | `Evse[]` | Array of EVSEs at this location. | | `operator` | `BusinessDetails` (optional) | The operator of the charge point. | | `last_updated` | `Date` | Timestamp of the last update. | Sources: [ocpi.location.v221.ts:223-250]() ### EVSE Schema An `Evse` (Electric Vehicle Supply Equipment) represents a single charge point, which can have one or more connectors. | Field | Type | Description | | -------------- | ------------------- | ------------------------------------------------------------------------ | | `uid` | `string` (max 39) | Uniquely identifies the EVSE within the CPO's platform. | | `evse_id` | `string` (max 48) | Compliant with eMI3 standard for public identification. | | `status` | `EvseStatus` (enum) | The current status of the EVSE (e.g., `AVAILABLE`, `CHARGING`). | | `capabilities` | `Capability[]` | An array of capabilities of the EVSE (e.g., `RESERVABLE`). | | `connectors` | `Connector[]` | A non-empty array of connectors on this EVSE. | | `last_updated` | `Date` | Timestamp of the last update. | Sources: [ocpi.location.v221.ts:133-149]() ### Connector Schema A `Connector` is the physical socket or cable outlet of an EVSE. | Field | Type | Description | | --------------------- | --------------------- | ------------------------------------------------------------------------ | | `id` | `string` (max 36) | Identifier of the connector on the EVSE. | | `standard` | `ConnectorType` (enum)| The standard of the connector (e.g., `IEC_62196_T2_COMBO`). | | `format` | `ConnectorFormat` (enum)| The format of the connector (`SOCKET` or `CABLE`). | | `power_type` | `PowerType` (enum) | The type of power provided (e.g., `AC_3_PHASE`, `DC`). | | `max_voltage` | `number` (integer) | The maximum voltage in volts. | | `max_amperage` | `number` (integer) | The maximum amperage in amperes. | | `last_updated` | `Date` | Timestamp of the last update. | Sources: [ocpi.location.v221.ts:74-84]() ## Sessions Module The Sessions module provides information about ongoing and recently completed charging sessions. A `Session` object is created when a charge is initiated and is updated throughout the process. This diagram outlines the structure of a `Session` object. ```mermaid classDiagram class Session { +string id +Date start_date_time +Date end_date_time +number kwh +CdrToken cdr_token +AuthMethod auth_method +SessionStatus status +ChargingPeriod[] charging_periods +Date last_updated } class CdrToken { +string uid +string contract_id } class ChargingPeriod { +Date start_date_time +CdrDimension[] dimensions } Session *-- "1" CdrToken : contains Session *-- "*" ChargingPeriod : contains ``` Sources: [ocpi.sessions.v221.ts:43-63](), [ocpi.sessions.v221.ts:24-28]() | Field | Type | Description | | ----------------- | ------------------------- | --------------------------------------------------------------------------- | | `id` | `string` (max 36) | The unique ID for the session. | | `start_date_time` | `Date` | The time when the session was started. | | `kwh` | `number` | The total energy consumed so far. | | `cdr_token` | `CdrToken` | The token used to authorize the session. | | `auth_method` | `AuthMethod` (enum) | Method used for authorization (`AUTH_REQUEST`, `COMMAND`, `WHITELIST`). | | `status` | `SessionStatus` (enum) | The current status of the session (`ACTIVE`, `COMPLETED`, `INVALID`, etc.). | | `charging_periods`| `ChargingPeriod[]` | An optional list of charging periods with detailed consumption data. | | `last_updated` | `Date` | Timestamp of the last update. | Sources: [ocpi.sessions.v221.ts:43-63]() ## CDRs (Charge Detail Records) Module A `Cdr` (Charge Detail Record) is the result of a charging session. It contains all the necessary information for billing and analysis. It is created after a session is completed. This diagram shows the main components of a `Cdr` object. ```mermaid classDiagram class Cdr { +string id +Date start_date_time +Date end_date_time +CdrToken cdr_token +CdrLocation cdr_location +string currency +Price total_cost +number total_energy +number total_time +ChargingPeriod[] charging_periods +Date last_updated } class CdrToken class CdrLocation class ChargingPeriod class Price Cdr *-- "1" CdrToken : contains Cdr *-- "1" CdrLocation : contains Cdr *-- "1..*" ChargingPeriod : contains Cdr *-- "1" Price : for total_cost ``` Sources: [ocpi.cdrs.v221.ts:86-116]() ### Cdr Schema | Field | Type | Description | | ------------------ | -------------------- | ------------------------------------------------------------------------ | | `id` | `string` (max 39) | The unique ID of the CDR. | | `start_date_time` | `Date` | The start time of the session. | | `end_date_time` | `Date` | The end time of the session. | | `cdr_token` | `CdrToken` | The token used for the session. | | `auth_method` | `AuthMethod` (enum) | The method used for authorization. | | `cdr_location` | `CdrLocation` | Details of the location where the charging took place. | | `currency` | `string` (length 3) | ISO-4217 currency code used for all costs. | | `charging_periods` | `ChargingPeriod[]` | A non-empty array detailing the consumption during the session. | | `total_cost` | `Price` | The total cost of the session. | | `total_energy` | `number` | The total energy consumed in kWh. | | `total_time` | `number` | The total duration of the session in decimal hours. | | `last_updated` | `Date` | Timestamp of the last update. | Sources: [ocpi.cdrs.v221.ts:86-116]() ### ChargingPeriod and CdrDimension The `charging_periods` array is crucial for billing. Each `ChargingPeriod` contains an array of `CdrDimension` objects, which specify what was consumed. The `CdrDimensionType` enum defines the possible dimensions that can be measured and billed: - `CURRENT` - `ENERGY` / `ENERGY_EXPORT` / `ENERGY_IMPORT` - `MAX_CURRENT` / `MIN_CURRENT` - `MAX_POWER` / `MIN_POWER` - `PARKING_TIME` - `POWER` - `RESERVATION_TIME` - `STATE_OF_CHARGE` - `TIME` Sources: [ocpi.cdrs.v221.ts:12-27]() ## Tariffs Module The Tariffs module defines the cost of charging. A `Tariff` object is composed of `TariffElement`s, which in turn contain `PriceComponent`s that specify the actual rates. This diagram shows the structure of a Tariff. ```mermaid erDiagram Tariff ||--|{ TariffElement : "has" TariffElement ||--|{ PriceComponent : "has" TariffElement }o--|| TariffRestrictions : "is restricted by" ``` Sources: [ocpi.tariff.v221.ts:100](), [ocpi.tariff.v221.ts:84]() A `Tariff` can be of different types, such as `REGULAR`, `AD_HOC_PAYMENT`, or profiles like `PROFILE_CHEAP` or `PROFILE_FAST`. Each `TariffElement` applies under certain `TariffRestrictions` (e.g., time of day, day of week, power level). | Field | Type | Description | | -------------- | ------------------- | ------------------------------------------------------------------------ | | `id` | `string` (max 36) | The unique ID of the tariff. | | `currency` | `string` (length 3) | ISO-4217 currency code. | | `type` | `TariffType` (enum) | The type of tariff. | | `elements` | `TariffElement[]` | A non-empty array of tariff elements that make up the price. | | `energy_mix` | `EnergyMix` | Optional details about the energy source mix for this tariff. | | `last_updated` | `Date` | Timestamp of the last update. | Sources: [ocpi.tariff.v221.ts:87-104]() ## Conclusion The `ocpi-schema` repository provides a robust and maintainable foundation for any developer working with OCPI v2.2.1. By defining all data structures as Zod schemas, it ensures type safety in TypeScript projects. The automated generation of standard JSON Schemas via the `ocpi.generate.ts` script extends these benefits to a wider range of platforms and languages, promoting interoperability and adherence to the OCPI standard. The clear, versioned, and modular structure of the schemas makes the repository easy to navigate and use. Sources: [README.md](), [ocpi.generate.ts]()