Errata
Thirty rough edges found in the S2 specification while implementing it — contradictions, typos on the wire, and gaps — with how s2-kit handles each one.On this page
Implementing a standard carefully means finding its rough edges. These are the ones this crate hit, each handled leniently and each worth an upstream issue.
Not all of them are in the text. E26 is in the standard’s own published examples: two of the four walkthroughs name identifiers they never define, which no schema validator can see because the values are legal identifiers, and no message-at-a-time validator can see because each message is faultless on its own.
Being the implementation that documents the standard’s rough edges is a deliverable, not a by-product. Every one of them is cited by number from the source code, so a surprising decision in the crate leads here rather than looking arbitrary.
A note on severity: where the standard is ambiguous, silent or self-contradictory, the corresponding validation rule is a warning rather than an error, and a warning never refuses traffic. A validator that rejects the standard’s own published examples is a bug, not a feature.
Abbreviations
| Citation | Means |
|---|---|
S2J | the S2 JSON schemas, v1.0.0 |
S2C | the S2 Connect specification, 1.0.0 |
S2C-OAS | the OpenAPI files of S2 Connect |
[s2-json #n] | an open issue on the S2 JSON tracker |
The list
| # | Where | Defect | How s2-kit handles it |
|---|---|---|---|
| E1 | S2J schemas/ID | Description: “An identifier expressed as a UUID”. Pattern: [a-zA-Z0-9\-_:]{2,64}, unanchored, in both v0.0.2-beta and v1.0.0. [s2-json #20] is open. s2energy’s vendored schema changed it to format: uuid and 0.3.0 made Id(Uuid) | Anchored pattern in strict mode; UUIDs generated by default, never required; upstream issue against s2-rust (R3) |
| E2 | S2J schemas/ControlType | The descriptions of FILL_RATE_BASED_CONTROL (“Identifier for the Demand Driven Based Control type”) and DEMAND_DRIVEN_BASED_CONTROL (“Identifier for the Fill Rate Based Control type”) are swapped | Docs pipeline override with citation (D2). Fixed upstream on s2-json main (PR #32, 2026-10-06) but not in any release: v1.0.0 — the version vendored and spoken — still has it, so the override stays until a tag carries the fix |
| E3 | S2J messages/PEBC.EnergyConstraint.lower_average_power | “Must be greater than or equal to lower_average_power” — copy‑pasted from upper; should read <= upper_average_power | Rule lower <= upper; docs override; upstream issue |
| E4 | S2J schemas/DDBC.OperationMode | The id field is spelled Id ([s2-json #15]) | #[serde(rename = "Id")] |
| E5 | S2J schemas/DDBC.ActuatorDescription | supported_commodites (typo) is the wire name | #[serde(rename = "supported_commodites")] |
| E6 | S2C §State of communication vs S2J schemas/RevokableObjects | The state table lists RevokeObject only in the RM column; RevokableObjects includes PEBC.Instruction, PPBC.*Instruction, OMBC.Instruction, FRBC.Instruction, DDBC.Instruction, which only the CEM sends | Accepted from both roles; sender/object‑type mismatch is a warning (D21); upstream issue |
| E7 | S2C §DNS-SD based discovery | The TXT record table names the key txtver; the avahi example on the same page writes txtvers=1 | Emit txtver=1, accept both (D13); upstream issue |
| E8 | S2C §Formal specification and versioning | Refers to s2-connect-connection-init.yml; the file is s2-connect-session-init.yml. The S2 JSON link points at the retired s2-ws-json/…/s2-json-schema path | Documentation only; upstream issue |
| E9 | S2C §Authentication vs S2C-OAS session-init | The prose calls the WebSocket bearer token commToken; the schema’s WebSocketCommunicationDetails has websocketToken and websocketUrl | Schema names used; documentation note |
| E10 | S2J messages/ReceptionStatus | For input with no message_id there is nothing to put in the required subject_message_id; the ecosystem uses the nil UUID ([s2-json #21]) | Emit the nil UUID; accept anything that parses as an ID |
| E11 | S2J messages/InstructionStatusUpdate | When each InstructionStatus must be sent, and in what order, is undocumented ([s2-json #26]) | Ledger accepts any order; regressions are warnings |
| E12 | S2J schemas/CommodityQuantity | Whether ELECTRIC.POWER.L1/L2/L3 and ELECTRIC.POWER.3_PHASE_SYMMETRIC may appear together is undocumented ([s2-json #25]) | Warning rule |
| E13 | Versioning | Every implementation negotiates "0.0.2-beta"; the schemas are tagged v1.0.0; S2 Connect wants the exact S2 JSON string | Profile table (D5) |
| E14 | structured-documentation/ReceptionStatusValues.toml | The INVALID_MESSAGE text ends in a stray “ß” | Docs override |
| E15 | S2J schemas/ControlType | NOT_CONTROLABLE is misspelled on the wire | Wire string kept verbatim via #[serde(rename = "NOT_CONTROLABLE")]; the Rust variant is spelled NotControllable — exactly what hems asked s2energy for (D24) |
| E16 | S2C §DNS-SD based discovery | The Deployment constraint “Can only be provided if the value for deployment is equal to LAN” is stated for longpollingUrl, but the TXT record carries no deployment key | Long‑polling is offered only by LAN endpoints by construction; documentation note |
| E17 | docs learn/examples/heat-pump | The worked example sends running_costs and transition_costs of zero in its FRBC.SystemDescription while its ResourceManagerDetails says “This heat pump does not define any costs related parameters, so no currency needs to be provided” — so currency is absent although cost fields are present | S2-RMD-002 is a warning, not an error: refusing the standard’s own example would make this crate stricter than the documentation it implements. Upstream issue |
| E18 | S2C §2. Calculate clientHmacChallengeResponse vs §Pairing token | The one-second delay and per-node serialisation are presented as the mitigation for brute force, but the first response hands the attacker an offline oracle: requestPairing returns R_c = HMAC(C_c, T ‖ F) for an attacker-chosen C_c, and F (the server’s leaf-certificate fingerprint) is public. One request is enough to recover a token offline — and the minimum for a dynamic token is four alphanumeric characters, 14.7 million candidates, which is seconds of GPU time. The rate limit bounds online guessing only | Both rules are implemented as specified, because they are normative. In addition PairingToken::parse refuses anything shorter than its kind allows, TokenKind::Dynamic is documented as the weaker of the two, and connect::proto’s documentation says plainly that a four-character dynamic token survives one reachable requestPairing. Upstream issue: the minimum for a dynamic token should be raised, or R_c withheld until after R_s is verified |
| E19 | S2C-OAS pairing/ConnectionDetails.certificateFingerprint vs §Challenge response process | ConnectionDetails carries a fingerprint of the CA certificate (“All fingerprints must refer to the same CA certificate”), while the HMAC binding uses the leaf: “F — SHA256 fingerprint of the TLS server certificate (i.e. leaf certificate)”. The two are a paragraph apart and named almost identically | Two distinct types: HmacBinding::LeafFingerprint for the binding, ConnectionDetails::certificate_fingerprint (a map, keyed by algorithm) for the pin. Conflating them yields a pairing that verifies and a connection that does not; documentation note on both |
| E20 | S2C-OAS pairing/PairingResponseErrorMessage | The enumeration has no member for the rate limit, although 503 is a documented response of the same operation, and none for an expired pairing attempt | ConnectError::RateLimited maps to 503 with no body, as the OpenAPI’s 503 has none; an expired attempt maps to 400 with Other. Upstream issue |
| E21 | S2C-OAS pairing/getNodes | GET /v1/nodes returns bare NodeDescriptions, which carry no NodeIdAlias — yet the alias is half of the pairing code the user types, and requestPairing accepts it as the way to name a node. A client that has browsed an endpoint therefore cannot map the alias the user typed onto the node it names; it can only send the alias and let the server resolve it | The client sends the alias and lets the server resolve it, which works; but a user interface cannot show “this code is for that charger” before pairing. Upstream issue: add nodeIdAlias to the getNodes response |
| E22 | S2C §4. HTTPS Client checks clientHmacChallengeResponse vs §Challenge response process | The client is told to “pin the self-signed CA (root) certificate” after the challenge succeeds — but the challenge binds the leaf, and a leaf says nothing about which CA signed it. A server could present a leaf whose fingerprint matches and a CA chosen freely, and the client would pin the attacker’s CA | The captured chain is recorded whole (CapturedIdentity), the leaf is what the HMAC checks, and the root of that same chain is what gets pinned — so the CA pinned is the one that signed the leaf the HMAC verified. Pinning a CA from any other source would be unsound. Upstream issue: say which certificate of the chain is pinned |
| E23 | S2C-OAS pairing/PairingAttemptId vs §Pairing | The attempt id is issued by requestPairing, which is unauthenticated, and the specification says only that “once the pairing process is finished (with or without success) the identifier can be discarded” — it never says what to do with one whose client walked away. A literal implementation accumulates an entry per abandoned attempt for the life of the process | Each entry carries the same fifteen-second budget as the attempt it names, and the map sweeps on insert. An expired id reads as unknown, which is a 401 — and S2C-OAS already says a 401 there lets the client restart, so the behaviour needed no new state |
| E24 | S2C §LAN-LAN only interactions | The subnet check is the only protection on operations that disclose every node an endpoint hosts and can make a device display its pairing code, yet it is specified as prose beside the operations rather than as a property of them. Nothing in the OpenAPI distinguishes the LAN-only paths from the authenticated ones | Two routers: router omits them entirely (so a WAN endpoint answers the recommended 404 for free) and lan_router mounts them but cannot be constructed without LocalSubnets. The check is a type requirement rather than a step to remember |
| E25 | S2C §Versioning of JSON Schema files vs S2J messages/Handshake | The same S2 JSON version is spelled two ways by the two specifications that negotiate it. S2 Connect says “the exact version string must be used (e.g. v1.0.0)” — with the v, matching the S2 JSON git tags — while every S2 JSON Handshake example, and every deployed implementation, writes 0.0.2-beta without one. Both negotiations are exact string matches, so the spellings do not interoperate. s2energy-connection’s own examples introduce a third form, MessageVersion("v1"), which is the API major version rather than a schema version at all | Transmit one spelling, understand both, in both negotiations. ProtocolVersion::matches compares the canonical form — an optional leading v stripped, and nothing else — and it is what Handshake/HandshakeResponse compare with as well as initiateSession. It is not a semver range: S2C requires an exact version, and s2energy parsing the peer’s string as a VersionReq is how an implementation ends up accepting a version the peer never offered (D5). What goes out depends on which specification is asking — WireProfile::version_str for an S2 JSON handshake, connect_version_str over S2 Connect. Upstream issue: the two documents should agree, and S2C should say the string is the S2 JSON tag |
| E26 | docs learn/examples/ev and learn/examples/heat-pump | Two of the four published walkthroughs contradict themselves. The EV conversation’s FRBC.ActuatorStatus carries the OpenAPI placeholder "string" where an operation-mode id belongs, while its own FRBC.SystemDescription declares om1 and om2. The heat-pump conversation declares actuator1 and then addresses actuator0 and actuator, and its InstructionStatusUpdate names instruction "string". Every one of these matches the ID pattern, so no schema validator sees them, and every message is faultless on its own, so no message-at-a-time validator does either | Found by session::Analyzer. The test suite asserts the five findings by name and exactly, and the fixtures are kept verbatim: a crate that corrects the standard’s examples to make its own tests pass has stopped testing against them. Upstream issue |
| E27 | S2C §Unpairing by the communication server vs S2C-OAS session-init | The unpairing section tells a client that “the next /[version]/initiateConnection HTTPS API request must fail with the No longer paired response”. There is no initiateConnection operation: the OpenAPI path is /initiateSession, and every other passage in the same document spells it that way. A reader implementing unpairing from this paragraph looks for an endpoint that does not exist — the sibling of E8, which is the same slip about a file name | Documentation only; the crate implements initiateSession, and SessionInitClient::unpaired is what drives it. Upstream issue |
| E28 | S2C-OAS pairing | The /finalizePairing path carries operationId: confirmPairing. Every other operation is named after its path, and a generator that names client methods from operationId — which is what generators do — produces a confirm_pairing for a /finalizePairing nobody can find by searching for it | The path is what goes on the wire and the path is what this crate uses; the operationId is named in a comment beside it. Upstream issue |
| E29 | S2C-OAS session-init/confirmAccessToken | The one POST in either file that defines no requestBody — the bearer is the whole message. Defensible, and also the kind of asymmetry a client written from the pattern rather than from the file gets wrong by posting an empty JSON document | No request body is sent. Posting null with a JSON content type is a body the specification does not define, and a peer validating against the OpenAPI may refuse it |
| E30 | S2J messages/ResourceManagerDetails.roles | roles is capped at maxItems: 3. There are three RoleTypes and four Commoditys, so the cap cannot be counting commodities — it is counting role types, and a resource may declare several roles for one commodity. The text never says so, nor what a CEM should do with more than one | Read as the cap reads. S2-RMD-003 reports only the repeated (role, commodity) pair; a battery declared as storage, consumer and producer of electricity is legal, which is the reading a CEM told only ENERGY_STORAGE needs |
| E31 | S2C-OAS pairing/ConnectionDetails.certificateFingerprint | The description says “The key "SHA265" must always be provided” — a digit transposed. The prose (S2C §8B), the challenge-response section and every implementation spell the key SHA256 | SHA256 is written and read (ConnectionDetails::SHA256); 6B details without it are refused. Upstream issue |
Reporting
Each entry marked “upstream issue” is filed against flexiblepower/s2-json, flexiblepower/s2-connect or flexiblepower/s2-documentation once the corresponding rule or override exists in code. Nothing here is a criticism of the standard as a whole: S2 is unusually well specified for its age, and a document this size having two dozen rough edges is ordinary. Writing them down is how they get fixed.