Data Models
This page focuses on the relationships between the database entities. For information about their attributes, you can find
them in citrineos-core/packages/dal.
Note that entities may appear more than once in the diagrams, depending on how they relate to the categories below and
the relationships described.
Tenants
Tenants represents all available tenants that CitrineOS recognizes. Every model has a tenantId FK, meaning
every model has a relationship to Tenants.
The one exception is ServerNetworkProfile.tenantId, where its tenantId is nullable since server profiles can exist
before a tenant is resolved (see Websocket Server Configurations -> dynamicTenantResolution in configurations).
Relevant Tables:
All of the tables.
Locations, Charging Stations, EVSEs, & Connectors
Location holds a pool of ChargingStations; each station exposes Evses; each Evse exposes Connectors.
StatusNotification is the append-only connector-status log, with LatestStatusNotification as a pointer to the newest
row per station.
Note that Evse is the physical/persistent EVSE record owned by a station, while EvseType is the OCPP 2.0.1 EVSEType
message component (an {id, connectorId} pair) used inside requests — it lives in the device model cluster and is referenced
by Reservation, TransactionEvent, Component and VariableAttribute. They are not the same table.
Relevant Tables
- Boot
- ChargingStationSecurityInfos
- ChargingStationSequences
- ChargingStations
- Connectors
- Evses
- EvseTypes
- LatestStatusNotifications
- Locations
- StatusNotifications
erDiagram
Location ||--|{ ChargingStation : "locationId - chargingPool"
ChargingStation ||--o{ Evse : "stationId"
ChargingStation ||--o{ Connector : "stationId"
Evse ||--o{ Connector : "evseId"
ChargingStation ||--o| Boot : "stationId"
ChargingStation ||--o{ ChargingStationSequence : "stationId"
ChargingStation ||--o{ ChargingStationSecurityInfo : "stationId"
ChargingStation ||--o{ StatusNotification : "stationId"
Connector ||--o{ StatusNotification : "connectorId"
ChargingStation ||--o{ LatestStatusNotification : "stationId"
StatusNotification ||--o| LatestStatusNotification : "statusNotificationId"
Connector ||--o{ EvseType : "connectorId"
Certificates
Certificate is the CSMS-side certificate store (self-referencing to model a signing chain). InstalledCertificate
mirrors what the station reports as installed; the two *Attempt tables log install/delete requests.
Relevant Tables
- Certificates
- ChargingStations
- DeleteCertificateAttempts
- InstallCertificateAttempts
- InstalledCertificates
erDiagram
Certificate ||--o{ Certificate : "signedBy - signingCertificate / signedCertificates"
Certificate ||--o{ InstalledCertificate : "certificateId"
Certificate ||--o{ InstallCertificateAttempt : "certificateId"
ChargingStation ||--o{ InstalledCertificate : "stationId"
ChargingStation ||--o{ InstallCertificateAttempt : "stationId"
ChargingStation ||--o{ DeleteCertificateAttempt : "stationId"
Security
Relevant Tables
- ChargingStations
- ChargingStationSecurityInfos
- SecurityEvents
erDiagram
ChargingStation ||--o{ ChargingStationSecurityInfo : "stationId"
ChargingStation ||--o{ SecurityEvent : "ocppConnectionName"
Network Profiles & Connectivity
ServerNetworkProfile describes a CSMS websocket endpoint; SetNetworkProfile records a SetNetworkProfile request
sent to a station; ChargingStationNetworkProfile is the join table binding a station's configuration slot to both.
Relevant Tables
- ChargingStationNetworkProfiles
- ChargingStations
- ServerNetworkProfiles
- SetNetworkProfiles
erDiagram
ChargingStation ||--o{ ChargingStationNetworkProfile : "stationId"
ServerNetworkProfile ||--o{ ChargingStationNetworkProfile : "websocketServerConfigId"
SetNetworkProfile ||--o{ ChargingStationNetworkProfile : "setNetworkProfileId"
ChargingStation ||--o{ SetNetworkProfile : "stationId"
ServerNetworkProfile ||--o{ SetNetworkProfile : "websocketServerConfigId"
ServerNetworkProfile ||--o{ ChargingStation : ""
ChargingStation }o--o{ ServerNetworkProfile : ""
Messaging, Reservations, and Operations
Relevant Tables
- AsyncJobStatuses
- ChangeConfigurations
- ChargingStations
- Components
- EvseTypes
- MessageInfos
- OCPPMessages
- Reservations
- SecurityEvents
- Subscriptions
- TenantPartners
- Tenants
erDiagram
ChargingStation ||--o{ OCPPMessage : "stationId"
OCPPMessage ||--o{ OCPPMessage : "requestMessageId"
Component ||--o{ MessageInfo : "displayComponentId"
EvseType ||--o{ Reservation : "evseId"
TenantPartner ||--o{ AsyncJobStatus : "tenantPartnerId"
Subscription }o--|| Tenant : "tenantId - webhook config"
SecurityEvent }o--|| Tenant : "tenantId"
ChangeConfiguration }o--|| Tenant : "tenantId - OCPP 1.6 key/value"
Device Model (OCPP 2.x)
The OCPP 2.x component/variable tree. Component x Variable is many-to-many through ComponentVariable; a concrete
reported value is a VariableAttribute (scoped to a station, component, variable and attribute type), and VariableStatus
is the per-attribute set/change result log.
Relevant Tables
- Boots
- ChargingStations
- Components
- ComponentVariables
- EvseTypes
- MessageInfos
- VariableAttributes
- VariableCharacteristics
- VariableStatuses
- Variables
erDiagram
Component }o--o{ Variable : "Joined via ComponentVariable"
Component ||--o{ ComponentVariable : "componentId"
Variable ||--o{ ComponentVariable : "variableId"
EvseType ||--o{ Component : "evseDatabaseId"
EvseType ||--o{ VariableAttribute : "evseDatabaseId"
ChargingStation ||--o{ VariableAttribute : "stationId"
Component ||--o{ VariableAttribute : "componentId"
Variable ||--o{ VariableAttribute : "variableId"
Boot ||--o{ VariableAttribute : "bootConfigId - pendingBootSetVariables"
VariableAttribute ||--o{ VariableStatus : "variableAttributeId"
Variable ||--o| VariableCharacteristics : "variableId"
Component ||--o{ MessageInfo : "displayComponentId"
Variable Monitoring & Events
VariableMonitoring is a monitor configured on a component/variable at a station; VariableMonitoringStatus logs
set/clear results; EventData is the inbound NotifyEvent payload.
Relevant Tables
- ChargingStations
- Components
- EventData
- VariableMonitoringStatuses
- VariableMonitorings
- Variables
erDiagram
ChargingStation ||--o{ VariableMonitoring : "stationId"
Component ||--o{ VariableMonitoring : "componentId"
Variable ||--o{ VariableMonitoring : "variableId"
VariableMonitoring ||--o{ VariableMonitoringStatus : "variableMonitoringId"
ChargingStation ||--o{ EventData : "stationId"
Component ||--o{ EventData : "componentId"
Variable ||--o{ EventData : "variableId"
VariableMonitoring ||..o{ EventData : "variableMonitoringId"
Transactions & Metering
Transaction is the main entity holding transaction information. OCPP 2.0.1 supplements it via TransactionEvent;
OCPP 1.6 supplements it via StartTransaction / StopTransaction. MeterValue attaches to whichever of the three is relevant.
Relevant Tables
- Authorizations
- ChargingNeeds
- ChargingStations
- Connectors
- Evses
- EvseTypes
- Locations
- MeterValues
- StartTransactions
- StopTransactions
- Tariff
- TransactionEvents
- Transactions
erDiagram
Location ||--o{ Transaction : "locationId"
ChargingStation ||--o{ Transaction : "stationId"
Evse ||--o{ Transaction : "evseId"
Connector ||--o{ Transaction : "connectorId"
Authorization ||--o{ Transaction : "authorizationId"
Tariff ||--o{ Transaction : "tariffId"
Transaction ||--o{ TransactionEvent : "transactionDatabaseId (OCPP 2.0.1)"
Transaction ||--o| StartTransaction : "transactionDatabaseId (OCPP 1.6)"
Transaction ||--o| StopTransaction : "transactionDatabaseId (OCPP 1.6)"
Transaction ||--o{ MeterValue : "transactionDatabaseId"
Transaction ||--o{ ChargingNeeds : "transactionDatabaseId"
TransactionEvent ||--o{ MeterValue : "transactionEventId"
StopTransaction ||--o{ MeterValue : "stopTransactionDatabaseId"
EvseType ||--o{ TransactionEvent : "evseId"
Connector ||--o{ StartTransaction : "connectorDatabaseId"
Connector ||--o{ MeterValue : "connectorId"
Tariff ||--o{ MeterValue : "tariffId"
Authorizations
Authorization represents ID Tokens. The LocalList* family is a separate, parallel copy used to build and version the
station-side local authorization list — it deliberately does not reuse Authorization rows.
Relevant Tables
- Authorizations
- LocalListAuthorizations
- LocalListVersionAuthorizations
- LocalListVersions
- SendLocalListAuthorizations
- SendLocalLists
- Tariffs
- TenantPartners
- Transactions
erDiagram
Authorization ||--o{ Authorization : "groupAuthorizationId (self - group token)"
Tariff ||--o{ Authorization : "tariffId"
TenantPartner ||--o{ Authorization : "tenantPartnerId"
Authorization ||--o{ Transaction : "authorizationId"
Authorization ||--o{ LocalListAuthorization : "authorizationId - source record"
Authorization ||--o{ LocalListAuthorization : "groupAuthorizationId - groupAuth"
LocalListVersion }o--o{ LocalListAuthorization : "Joined via LocalListVersionAuthorization"
LocalListVersion ||--o{ LocalListVersionAuthorization : "localListVersionId"
LocalListAuthorization ||--o{ LocalListVersionAuthorization : "authorizationId"
SendLocalList }o--o{ LocalListAuthorization : "Joined via SendLocalListAuthorization"
SendLocalList ||--o{ SendLocalListAuthorization : "sendLocalListId"
LocalListAuthorization ||--o{ SendLocalListAuthorization : "authorizationId"
Tariffs
Tariff represents a pricing tariff.
Note that SalesTariff in Smart Charging is unrelated — it is the OCPP ISO 15118 SalesTariff element attached
to a charging schedule, not a pricing record.
Relevant Tables
- Authorizations
- Connectors
- MeterValues
- Tariffs
- Transactions
erDiagram
Tariff ||--o{ Connector : "tariffId"
Tariff ||--o{ Transaction : "tariffId"
Tariff ||--o{ MeterValue : "tariffId - price snapshot per reading"
Tariff ||--o{ Authorization : "tariffId - token-specific tariff"
Smart Charging
ChargingProfile → ChargingSchedule → SalesTariff is the OCPP profile tree. ChargingNeeds captures NotifyEVChargingNeeds;
CompositeSchedule stores a computed GetCompositeSchedule result.
Relevant Tables
- ChargingNeeds
- ChargingProfiles
- ChargingSchedules
- CompositeSchedules
- Evses
- Transactions
erDiagram
ChargingProfile ||--o{ ChargingSchedule : "chargingProfileDatabaseId"
Transaction ||--o{ ChargingProfile : "transactionDatabaseId"
ChargingSchedule ||--o{ SalesTariff : "chargingScheduleDatabaseId"
SalesTariff ||--o{ ChargingSchedule : "salesTariffId"
Evse ||--o{ ChargingNeeds : "evseId"
Transaction ||--o{ ChargingNeeds : "transactionDatabaseId"
Evse ||--o{ CompositeSchedule : "evseId"
Pure OCPP 1.6 vs 2.x models
1.6-only
ChangeConfiguration
Connector
StartTransaction
StopTransaction
2.x-only
ChargingNeeds
Component
EventData
EvseType
InstalledCertificate
LocalListVersion
MessageInfo
SalesTariff
SendLocalList
SetNetworkProfile
TransactionEvent
Variable
VariableAttribute
VariableCharacteristics
VariableMonitoring
VariableMonitoringStatus
VariableStatus
Shared
Authorization
Boot
ChargingProfile
ChargingSchedule
ChargingStation
MeterValue
OCPPMessage
Reservation
StatusNotification
Transaction