Open Charge Point Protocol Reference

A structured OCPP reference for AI agents and developers building EV charging infrastructure. Covers OCPP 2.0.1 and OCPP 1.6J with field-level message schemas, sequence diagrams, smart charging deep-dives, and explicit markers for every place the spec leaves a decision to you.

Source on GitHub.

#Why This Exists

OCPP specifications are hundreds of pages long and full of deliberate gaps — places where behavior depends on your hardware vendor, your business rules, or your grid operator's requirements. AI coding agents that rely on training data alone tend to fill those gaps with plausible-sounding defaults. Sometimes they're right. Often they're not, and you don't find out until production.

OCPP.md gives AI agents (and human developers) a structured reference that distinguishes between what the spec defines, what it intentionally leaves open, and what depends on your specific deployment. Every ambiguous area is marked with an escalation marker — the agent stops and asks you instead of guessing.

#Using with AI Agents

#Claude Code

Install as a plugin:

/plugin marketplace add https://github.com/alexeimoisseev/ocpp.md
/plugin install ocpp@ocpp

Then use /ocpp <topic> to load specific reference material, or just ask OCPP-related questions — the plugin activates automatically when it detects OCPP keywords in your code or prompts.

#Other Agents (Cursor, Windsurf, Copilot, etc.)

Clone the repository and point your agent at the docs/ directory. See the AI Agent Setup Guide for detailed instructions.

#OCPP 2.0.1

The current specification, recommended for all new deployments. 64 messages organized by Functional Block.

Reference docs:

• OCPP 2.0.1 Overview & Architecture — Roles, device model, transport, message frame, all 64 messages
• Shared Data Types — 34 enums and composite types used across messages

Schemas (field-level, generated from OCA JSON schemas):

• Provisioning — BootNotification, GetVariables, SetVariables, Reset, etc.
• Authorization — Authorize, SendLocalList, ClearCache
• Transactions — TransactionEvent, RequestStartTransaction, MeterValues
• Smart Charging — SetChargingProfile, GetCompositeSchedule, etc.
• Firmware — UpdateFirmware, FirmwareStatusNotification
• Security — CertificateSigned, InstallCertificate, SecurityEventNotification
• Diagnostics — GetLog, NotifyEvent, SetVariableMonitoring
• Availability — ChangeAvailability, StatusNotification, Heartbeat
• Reservation — ReserveNow, CancelReservation
• Display — SetDisplayMessage, CostUpdated

Behavioral docs:

• Sequences — Boot, authorization, transaction lifecycle, offline replay
• Sequences (Operational) — Firmware updates, diagnostics, reset
• Smart Charging Deep-Dive — Profile model, composite schedules, AC/DC differences
• Smart Charging Examples — Worked examples with full JSON payloads
• Smart Charging & ISO 15118 — EV-side schedules, Plug & Charge integration
• Charging Profile Generator — Interactive tool to build SetChargingProfileRequest payloads

#OCPP 1.6J

The most widely deployed version. 28 messages organized by Feature Profile. Uses JSON over WebSocket transport (the "J" suffix).

Reference docs:

• OCPP 1.6J Overview & Architecture — Roles, connector model, transport, all 28 messages, config keys, differences from 2.0.1

Schemas (field-level, generated from OCA JSON schemas):

• Core — BootNotification, Authorize, StartTransaction, StopTransaction, StatusNotification, etc. (16 messages)
• Smart Charging — SetChargingProfile, ClearChargingProfile, GetCompositeSchedule
• Firmware — UpdateFirmware, GetDiagnostics, status notifications
• Local Auth List — SendLocalList, GetLocalListVersion
• Reservation — ReserveNow, CancelReservation
• Remote Trigger — TriggerMessage

Behavioral docs:

• Sequences — Boot, authorization, transaction lifecycle, status reporting, offline behavior
• Smart Charging Deep-Dive — Profile purposes, stack levels, composite schedule, common pitfalls
• Charging Profile Generator — Interactive tool to build SetChargingProfile.req payloads

#The Escalation Model

This is the core idea behind OCPP.md. Both OCPP specifications have areas where behavior is intentionally left to the implementer. Most AI agents treat these like any other requirement and quietly make something up. OCPP.md marks every such area so the agent knows to ask:

• SPEC-SILENT — The specification doesn't define this. You need to make a decision.
• VENDOR-DEPENDENT — Behavior varies by charging station hardware or firmware. Ask which hardware you're targeting.
• POLICY-DEPENDENT — Depends on business rules, site configuration, or grid operator requirements.

By default, the agent stops and asks. If you want it to pick reasonable defaults during prototyping, add this to your project configuration (e.g., CLAUDE.md):

For OCPP: use pragmatic escalation mode.

#About This Project

• Source: github.com/alexeimoisseev/ocpp.md
• Methodology: All schemas are mechanically extracted from official OCA JSON schemas. Behavioral docs are AI-authored with explicit confidence tiers. See Methodology.
• License: Apache 2.0. Does not redistribute the official OCPP specification.
• Disclaimer: Non-normative documentation. Always verify against the official specification and your vendor's documentation. OCPP is a trademark of the Open Charge Alliance. This project is not affiliated with or endorsed by the OCA.