From d32148ae0ac6df1743de5e56f1e9f49fd9dac32b Mon Sep 17 00:00:00 2001 From: xBlaz3kx Date: Thu, 7 May 2026 19:53:20 +0200 Subject: [PATCH] docs: adding comprehensive documentation for usage --- README.md | 8 +++ docs/custom-schemas.md | 50 ++++++++++++++ docs/remote-registry.md | 130 +++++++++++++++++++++++++++++++++++++ docs/validate-from-file.md | 39 +++++++++++ 4 files changed, 227 insertions(+) create mode 100644 docs/custom-schemas.md create mode 100644 docs/remote-registry.md create mode 100644 docs/validate-from-file.md diff --git a/README.md b/README.md index 68598da..bd797d2 100644 --- a/README.md +++ b/README.md @@ -56,6 +56,8 @@ Available Commands: Flags: -d, --debug Enable debug mode -h, --help help for chargeflow + -m, --model string Charging-station model for vendor/model-specific schema selection + -V, --vendor string Charging-station vendor for vendor/model-specific schema selection -v, --version string OCPP version to use (1.6, 2.0.1 or 2.1) (default "1.6") ``` @@ -72,6 +74,12 @@ Additionally, you can specify a custom path to vendor-specific OCPP schemas usin > You can also validate multiple OCPP messages from a file using the `-f` flag. > The file should be a newline-separated list of JSON strings. +For more detailed usage, see the documentation: + +- [Validating messages from a file](docs/validate-from-file.md) +- [Custom and vendor-specific schemas](docs/custom-schemas.md) +- [Remote schema registry](docs/remote-registry.md) + ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details. diff --git a/docs/custom-schemas.md b/docs/custom-schemas.md new file mode 100644 index 0000000..2ddfc70 --- /dev/null +++ b/docs/custom-schemas.md @@ -0,0 +1,50 @@ +# Custom and vendor-specific schemas + +ChargeFlow ships with built-in schemas for all supported OCPP versions. You can extend or override +these with your own JSON schemas to handle vendor-specific extensions or non-standard field +constraints. + +## Vendor- and model-specific validation + +Pass `--vendor` (`-V`) and/or `--model` (`-m`) to select schemas scoped to a specific charging +station. When both flags are provided, ChargeFlow looks for schemas registered under that +vendor/model combination before falling back to the standard built-in schemas. + +```bash +chargeflow --vendor Acme --model FastCharger validate \ + '[2, "1", "BootNotification", {"chargePointVendor": "Acme", "chargePointModel": "FastCharger"}]' +``` + +## Loading schemas from a local directory + +Use `--schemas` (`-a`) on the `validate` command to point ChargeFlow at a folder of custom JSON +schema files. File names must match the OCPP action name they cover, e.g. +`BootNotificationRequest.json`. Custom schemas **replace** the built-in schemas for the actions +they cover. + +```bash +chargeflow validate --schemas ./vendor-schemas \ + '[2, "1", "BootNotification", {"chargePointVendor": "Acme", "chargePointModel": "FastCharger"}]' +``` + +Combining vendor/model flags with a custom schema folder is the typical pattern for validating +messages from a specific charging station: + +```bash +chargeflow --vendor Acme --model FastCharger \ + validate --schemas ./vendor-schemas -f messages.txt -o report.json +``` + +## Schema file naming convention + +Schema files must be named after the OCPP action with a `.json` extension: + +``` +BootNotificationRequest.json +BootNotificationResponse.json +DataTransfer.json +... +``` + +ChargeFlow strips the `.json` suffix and uses the remaining string as the action name when +registering the schema internally. \ No newline at end of file diff --git a/docs/remote-registry.md b/docs/remote-registry.md new file mode 100644 index 0000000..9742f10 --- /dev/null +++ b/docs/remote-registry.md @@ -0,0 +1,130 @@ +# Remote schema registry + +ChargeFlow can push schemas to and remove schemas from a Kafka-compatible schema registry such as +[Confluent Schema Registry](https://docs.confluent.io/platform/current/schema-registry/index.html) +or [Redpanda Schema Registry](https://docs.redpanda.com/current/manage/schema-reg/). + +All `schema` subcommands share a set of common flags for the registry URL and authentication. + +## Common flags + +| Flag | Description | Default | +|------|-------------|---------| +| `--url` | Remote schema registry URL (required) | — | +| `--auth-type` | Authentication type: `basic`, `bearer`, `api-key`, or omit for none | — | +| `--username` | Username for basic authentication | — | +| `--password` | Password for basic authentication | — | +| `--bearer-token` | Bearer token | — | +| `--api-key` | API key value | — | +| `--api-key-header` | Header name for the API key | `X-API-Key` | +| `--custom-header` | Custom header name | — | +| `--custom-value` | Custom header value | — | +| `--timeout` | Request timeout | `5s` | + +## Registering schemas + +Use `schema register` to upload JSON schemas to the registry. + +### Register a single schema file + +`--action` is required when registering a single file. + +```bash +chargeflow schema --url http://localhost:8081 \ + register --file BootNotificationRequest.json --action BootNotificationRequest +``` + +### Register all schemas from a directory + +ChargeFlow reads every `.json` file in the directory and derives the action name from the file name. + +```bash +chargeflow schema --url http://localhost:8081 --version 2.0.1 \ + register --dir ./schemas +``` + +### Register vendor-specific schemas + +Supply `--vendor` and `--model` on the root command to scope the schemas to a specific charging +station make and model. + +```bash +chargeflow --vendor Acme --model FastCharger \ + schema --url http://localhost:8081 \ + register --dir ./vendor-schemas +``` + +## Deleting schemas + +Use `schema remove` to delete schemas from the registry. Exactly one of `--action`, `--file`, or +`--dir` must be specified. + +### Delete by action name + +```bash +chargeflow schema --url http://localhost:8081 \ + remove --action BootNotificationRequest +``` + +### Derive the action from a file name + +ChargeFlow strips the `.json` suffix and uses the result as the action name. + +```bash +chargeflow schema --url http://localhost:8081 \ + remove --file BootNotificationRequest.json +``` + +### Delete all schemas matching a directory + +Removes every schema whose action name matches a `.json` file found in the directory. + +```bash +chargeflow schema --url http://localhost:8081 \ + remove --dir ./schemas +``` + +### Delete vendor-specific schemas + +```bash +chargeflow --vendor Acme --model FastCharger \ + schema --url http://localhost:8081 \ + remove --action DataTransfer +``` + +## Authentication examples + +### Basic authentication + +```bash +chargeflow schema --url http://registry:8081 \ + --auth-type basic --username admin --password secret \ + register --dir ./schemas +``` + +### Bearer token + +```bash +chargeflow schema --url https://registry.example.com \ + --auth-type bearer --bearer-token eyJ... \ + register --file MySchema.json --action MyAction +``` + +### API key + +The default header is `X-API-Key`. Override it with `--api-key-header` if your registry uses a +different header name. + +```bash +chargeflow schema --url https://registry.example.com \ + --auth-type api-key --api-key abc123 \ + register --dir ./schemas +``` + +### Custom header + +```bash +chargeflow schema --url https://registry.example.com \ + --custom-header X-Registry-Auth --custom-value my-secret \ + register --dir ./schemas +``` \ No newline at end of file diff --git a/docs/validate-from-file.md b/docs/validate-from-file.md new file mode 100644 index 0000000..18fda1c --- /dev/null +++ b/docs/validate-from-file.md @@ -0,0 +1,39 @@ +# Validating messages from a file + +Use the `-f` flag to read OCPP messages from a file instead of passing them as a command-line +argument. Each line must be a single, complete OCPP JSON string; blank lines are ignored. + +```bash +chargeflow validate -f messages.txt +``` + +Example `messages.txt`: + +``` +[2, "1", "BootNotification", {"chargePointVendor": "TestVendor", "chargePointModel": "TestModel"}] +[2, "2", "Heartbeat", {}] +[3, "1", {"status": "Accepted", "currentTime": "2024-01-01T00:00:00Z", "interval": 300}] +``` + +> [!NOTE] +> Response messages (type `3`) require the `--response-type` flag so ChargeFlow knows which schema +> to validate against, e.g. `--response-type BootNotificationResponse`. + +## Saving the report to a file + +Use `-o` to write the validation report to a file instead of stdout. Supported extensions are +`.json`, `.csv`, and `.txt`. + +```bash +chargeflow validate -f messages.txt -o report.json +chargeflow validate -f messages.txt -o report.csv +chargeflow validate -f messages.txt -o report.txt +``` + +## Specifying the OCPP version + +The default version is `1.6`. Use `--version` (`-v`) to change it. + +```bash +chargeflow --version 2.0.1 validate -f messages.txt -o report.json +``` \ No newline at end of file