Skip to content

[#643] Remove the protobuf extension ranges - #650

Merged
wes-johnson merged 1 commit into
eclipse-sparkplug:developfrom
wes-johnson:643
Nov 4, 2026
Merged

wes-johnson merged 1 commit into
eclipse-sparkplug:developfrom
wes-johnson:643

Conversation

@wes-johnson

Copy link
Copy Markdown
Contributor

Closes #643. Per the spec team decision to remove them.

Stacked on #649 — it is based on that branch because #649 adds a ValueArray whose range would
otherwise need removing separately, and both touch the same messages. Merge after it.

What is removed

  • All 16 extension ranges, one per message
  • TypedValueExtension, a message that existed only to host a range
  • The extension_value arm of the TypedValue oneof
  • The three JSON statements that defined how an extension appears in JSON

array_value takes field number 16, which the extension arm freed, rather than leaving a gap at
16 with the array sitting at 17.

Why

Never used. No extend statement anywhere in the specification, Tahu 3.x, Tahu develop or the
TCK, and no hand-written call to the extension API in any of them — after three major versions of
being reserved.

Not free. Six changes during v4 development moved a floor: typed Commands (#441/#442), the
metadata separation (#445/#448), the topic namespace change (#598), the header/content split (#622),
TemplateList (#450), and the ValueArray in #649. Each was a theoretical break for a third party
occupying the numbers being vacated, for no third party that exists.

Did not work in JSON. The Protocol Buffers JSON Mapping is specified for proto3, which has no
extensions, so #645 had to invent payloads-json-extension-key, -extension-value and
-extension-ignore to define the bracketed [fully.qualified.name] form. Even then an extension
survived a binary round trip but not a JSON one, because an unrecognized key is dropped on output
and rejected on input — so a third party's field lived on spCv4.0 and vanished on spJv4.0.

Those three statements go with the mechanism. The rationales that leaned on extension ranges — in
the ignore-unknown comment and the self-contained note — are reworded to rest on the ordinary
protobuf unknown-field rule instead, which is what actually provides forward compatibility.

Not a wire change

For anything that exists. A payload exercising metrics, a DataSet and a null cell:

with extension ranges : 72 bytes
without               : 72 bytes
BYTE-IDENTICAL        : True
each decodes the other: True

Extension ranges are declarations; removing them changes no encoded byte. The only source-visible
change is array_value moving 17 → 16, which is free because spCv4.0 is unreleased.

If a third party does need this later

Nothing is foreclosed. Field numbers can be reserved before any are consumed, and the options
measured on #643 remain available — reserved N to max to claim numbers, or a declared
google.protobuf.Struct field, which unlike the ranges works in both encodings and round-trips.
Neither needs to be decided now, which is the point of removing a mechanism nobody has asked for.

Verification

Build passes; schema compiles under protoc. JSON Schema valid draft 2020-12, 22/22 example
payloads validate, 15/15 negative tests behave as specified. Broken-anchor (10) and tck-id-anomaly
(7) baselines unchanged. No extension reference remains anywhere in the specification text.

Per the spec team decision. All 16 extension ranges are removed, along with the
TypedValueExtension message, which existed only to host one, and the
extension_value arm of the TypedValue oneof.

They had never been used. There is no extend statement anywhere in the
specification, Tahu 3.x, Tahu develop or the TCK, and no hand-written call to the
extension API in any of them, after three major versions of being reserved.

They were not free. Six changes in v4 development moved a floor - typed Commands,
the metadata separation, the topic namespace change, the header/content split,
TemplateList, and the ValueArray in eclipse-sparkplug#649 - each a theoretical break for any third
party occupying the numbers being vacated, for no actual third party.

They also did not work in the JSON encoding. The Protocol Buffers JSON Mapping is
specified for proto3, which has no extensions, so eclipse-sparkplug#645 had to invent three
statements defining the bracketed key form, and an extension still survived a
binary round trip but not a JSON one. Those three statements are removed with the
mechanism, and the rationales that rested on extension ranges are reworded to
rest on the ordinary unknown-field rule instead.

array_value takes field number 16, which the extension arm freed, rather than
leaving a gap at 16 with the array at 17.

Not a wire change for anything that exists: a payload exercising metrics, a
DataSet and a null cell serializes byte-identically under both schemas, and each
decodes the other's output.
@wes-johnson
wes-johnson merged commit db02c3c into eclipse-sparkplug:develop Nov 4, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants