Skip to content

[#651] Describe TypedValue once instead of three divergent times - #653

Merged
wes-johnson merged 4 commits into
eclipse-sparkplug:developfrom
wes-johnson:651
Nov 9, 2026
Merged

wes-johnson merged 4 commits into
eclipse-sparkplug:developfrom
wes-johnson:651

Conversation

@wes-johnson

@wes-johnson wes-johnson commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Addresses #651, except for the part that depends on #652.

The problem

Since #429 the schema has carried a single reusable Payload.TypedValue, consumed by Metric.value, PropertySet.values and Template.Parameter.typed_value. The chapter text never followed. It still hand-maintained three separate lists of which types a value may be, and no two agreed — with each other or with the 14-arm oneof:

Metric Property Parameter
int32 / int64 missing listed listed
uint32/uint64/float/double/bool/string/bytes listed listed listed
DataSet listed listed missing
Template listed missing missing
PropertySet / PropertySetList missing listed missing
ValueArray missing missing missing

The change

Adds a payloads_c_typedvalue section that describes the structure once — datatype, is_null, and the complete set of value arms — and replaces the Metric and PropertyValue enumerations with references to it. One structure, one description.

Two real defects disappear along with the duplication:

  • The Metric list omitted int32 and int64. The correct field for an Int32 or Int64 metric was named nowhere in the Metric section.
  • No list included ValueArray, while payloads-array-value-array normatively requires a Metric with an array datatype to carry its elements in array_value. The chapter required a field its own value lists excluded. This was meant to land in [#642] [#648] Carry arrays in a ValueArray, with nulls recorded by index #649 but was pushed a day after that PR merged, so it never reached develop; it lands here instead.

The section ends with a non-normative note saying that a context may accept only part of the set, and that any such restriction is stated in that context's own section rather than by restating the list — so this does not recur.

A second staleness of the same pedigree

Three assertions said the datatype MUST be an unsigned 32-bit integer:

  • tck-id-payloads-metric-datatype-value-type
  • tck-id-payloads-metric-propertyvalue-type-type
  • tck-id-payloads-template-parameter-value-type

That described the pre-#552 messages, where Metric, PropertyValue and Template.Parameter each carried their own uint32 type field. Since the oneofs were consolidated the datatype lives in TypedValue and is the DataType enumeration — and in the JSON encoding it is normally the datatype's name, not a number, which the JSON Schema allows ({"oneOf": [{"type": "string"}, {"type": "integer", "minimum": 0}]}) and every example in the chapter uses. So the wording was wrong for both encodings.

All three now say the datatype MUST be a value of the DataType enumeration, leaving the representation to the encoding in use.

Two editorial fixes ride along: the PropertyValue bullet is renamed from type to datatype, matching the field it describes, and int64_ in the template parameter list regains its missing leading underscore so it renders in italics (introduced in #62, March 2025).

What is deliberately not here

The Template Parameter nine-type restriction is untouched. Its nine permitted types are a normative MUST (tck-id-payloads-template-parameter-value) that conflicts with the schema, and whether that restriction is intentional or an artifact of the pre-#429 oneof is the subject of #652. The answer decides whether that section ends up carrying a restriction or a reference, so it should be settled first rather than guessed at here.

Review fixes (22bad02)

  • Restored a restriction the consolidation dropped. The removed Metric prose was normative though untagged, and its list excluded PropertySet and PropertySetList. Pointing at the full TypedValue set made a Metric with datatype PropertySet conforming, which it was not before — a silent widening in a PR meant to change nothing normative. Now tck-id-payloads-metric-datatype-not-propertyset in the Metric section, which is what the closing note says a context's restriction should do. It adds a tck-id with no TCK coverage yet.
  • Linked the datatype assertions to the JSON rule. My earlier claim that the chapter had no rule for representing datatype in JSON was wrong: tck-id-payloads-json-enum-name and -enum-accept already say it, in payloads_json_scalar. All three assertions now point there, and that paragraph is removed from this description.
  • Split the Metric pair. -datatype-value-type is now about the representation only, leaving legal values to -datatype-value, so they are no longer one requirement under two ids. The PropertyValue and Template Parameter pairs genuinely differ and are unchanged.
  • The TypedValue section points at the datatype/is_null agreement rule and the JSON flattening, and the closing note carries an example.
  • Three stale assertion texts in SendComplexDataTest that still quoted the old wording are updated.

Separately, SendComplexDataTest:405 logs the datatype assertion text against ID_PAYLOADS_PROPERTYSET_KEYS_ARRAY_SIZE, which does not correspond to it. It predates this PR and is debug-only, so I left it rather than guess at the intended id.

Verification

Build passes. Broken-anchor (11) and tck-id-anomaly (7) baselines unchanged, measured against develop. No new link:# targets that do not resolve; payloads_c_typedvalue and payloads_c_datatype_array both verified to exist. Exactly one type enumeration remains in the chapter, in the new section. No added line exceeds 100 columns.

…ergent times

The schema carries a single reusable TypedValue, but the chapter still
hand-maintained three lists of which types a value may be, and no two
agreed with each other or with the oneof.

Adds a TypedValue section describing the structure once, with the
complete set of arms, and replaces the Metric and PropertyValue
enumerations with references to it. Two defects go away with them:

- The Metric list omitted int32 and int64, so the correct field for an
  Int32 or Int64 metric was named nowhere in that section.
- Neither list included ValueArray, while payloads-array-value-array
  normatively requires a Metric with an array datatype to carry its
  elements in array_value. The chapter required a field its own value
  lists excluded.

The Template Parameter list is deliberately left alone: whether its
nine-type MUST is intentional or an artifact of the pre-eclipse-sparkplug#429 oneof is
the subject of eclipse-sparkplug#652, and the answer decides whether that section ends
up carrying a restriction or a reference.
…t integer

Three assertions said the datatype MUST be an unsigned 32-bit integer.
That described the pre-eclipse-sparkplug#552 messages, where Metric, PropertyValue and
Template.Parameter each carried their own uint32 type field. Since the
oneofs were consolidated the datatype lives in TypedValue and is the
DataType enumeration, and in the JSON encoding it is normally the
datatype's name rather than a number, so the wording was wrong for
both encodings.

All three now say the datatype MUST be a value of the DataType
enumeration, leaving the representation to the encoding in use.

Also renames the PropertyValue bullet from type to datatype, matching
the field it describes, and restores the missing leading underscore on
int64_ in the template parameter list so it renders in italics.

The nine-type restriction on template parameters is untouched; that is
the subject of eclipse-sparkplug#652.

@nathandavenport nathandavenport left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed at 03b769f against develop 83bf202: the diff, the full chapter at head, and the TCK sources that use the three reworded ids. Not built locally. CI (Build, Gradle Wrapper) is green.

Good change. The table in the description checks out against develop, all eleven link:# targets resolve, and the consolidated section matches the 14-arm oneof. Leaving the nine-type Template Parameter restriction to #652 is the right call.

Four optional comments inline, none blocking:

  • The JSON rule the description says is missing already exists: tck-id-payloads-json-enum-name / -enum-accept. Worth linking from the three reworded assertions and dropping that paragraph from the description.
  • For Metric, -datatype-value-type and -datatype-value now say the same thing.
  • The new TypedValue section could point at the Metric datatype/is_null agreement rule and the JSON flattening.
  • An example in the closing note would make its intent clearer.

Outside the diff (optional): SendComplexDataTest.java lines 355, 405 and 423 still log "MUST be an unsigned 32-bit integer representing the datatype". The generated Requirements constants pick up the new text, so only those debug lines are stale.
4 optional suggestion(s) are included. They are not required for approval.

@ckienle ckienle left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. One structure described once is the right shape. The new section matches the 14-arm oneof, the link targets resolve, and the datatype wording is right for both encodings. Keeping the Parameter bullet as type is also correct, since that's the JSON key tck-id-payloads-json-typedvalue-parameter-keys requires.

I agree with Nathan's four optionals, the JSON enum-name link in particular. One more optional inline, on the Metric value bullet, that his comments don't cover.

…restriction

Addresses the review on eclipse-sparkplug#653.

- Restores the restriction the consolidation dropped. The removed
  Metric prose was normative though untagged, and its list excluded
  PropertySet and PropertySetList. Referring to the full TypedValue set
  made a Metric with datatype PropertySet conforming, which it was not
  before. Now stated as its own assertion in the Metric section, which
  is what the closing note says a context's restriction should do.
- Links the three datatype assertions to the Scalar Value Mapping
  section. The JSON representation rule already exists there
  (payloads-json-enum-name, payloads-json-enum-accept); the claim in
  the PR description that none existed was wrong.
- Narrows payloads-metric-datatype-value-type to the representation,
  leaving which values are legal to payloads-metric-datatype-value, so
  the two are no longer one requirement under two ids.
- The TypedValue section now points at the datatype and is_null
  agreement rule and the JSON flattening, and the closing note carries
  an example.
- Updates three stale assertion texts in SendComplexDataTest that still
  quoted the old unsigned 32-bit integer wording.

@nathandavenport nathandavenport left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed at 22bad02. All four of my earlier comments are addressed, the two new link:# targets resolve (payloads_json_scalar, payloads_json_typed_values), and restoring the PropertySet restriction as its own tagged assertion keeps the PR non-normative. CI is green. Not built locally.

Two small optional comments inline, none blocking:

  • The new agreement paragraph uses an untagged "MUST" that repeats the tagged tck-id-payloads-typedvalue-datatype-agree.
  • SendComplexDataTest.java:408 logs the datatype text under the PropertySet keys-array-size id (pre-existing, now more visible).
    2 optional suggestion(s) are included. They are not required for approval.

…matched log line

- The agreement paragraph added in 22bad02 stated the requirement with
  an untagged MUST, repeating tck-id-payloads-typedvalue-datatype-agree
  and reintroducing exactly the pattern this PR removed from the Metric
  prose. It now refers to the tagged rule instead of restating it.
- Removes the debug line in checkPropertiesValidType that logged the
  datatype assertion text under ID_PAYLOADS_PROPERTYSET_KEYS_ARRAY_SIZE.
  The keys-array-size rule is already logged correctly a few lines
  below, so the line was both mismatched and redundant.
@wes-johnson

Copy link
Copy Markdown
Contributor Author

Pushed 43480dd. All seven review comments across both passes are addressed and every thread is resolved.

Second pass (43480dd)

  • The agreement paragraph I added in 22bad02 stated the requirement with an untagged MUST, repeating tck-id-payloads-typedvalue-datatype-agree. That is the same pattern this PR removed from the Metric prose, reintroduced four sections earlier in the same change. It now refers to the tagged rule instead of restating it.
  • Removed the debug line in checkPropertiesValidType that logged the datatype text under ID_PAYLOADS_PROPERTYSET_KEYS_ARRAY_SIZE. I had flagged this and left it rather than guess the intended id; deleting it is the better answer, since the keys-array-size rule is already logged correctly a few lines below. The line was redundant as well as mismatched.

First pass (22bad02)

  • Restored the restriction the consolidation dropped, as tck-id-payloads-metric-datatype-not-propertyset. This was the one real defect in the review: the deleted Metric prose was normative though untagged, and referring to the full TypedValue set silently made a Metric with datatype PropertySet conforming when it had not been.
  • Linked the three datatype assertions to payloads_json_scalar. My claim in the description that no JSON rule existed was wrong — tck-id-payloads-json-enum-name and -enum-accept already say it.
  • Split -datatype-value-type (representation) from -datatype-value (legal values) for Metric.
  • Pointed the TypedValue section at the agreement rule and the JSON flattening, and added an example to the closing note.
  • Updated three stale assertion texts in SendComplexDataTest.

Verification: build successful; broken-anchor (11) and tck-id-anomaly (7) baselines unchanged against develop; the new assertion id appears exactly twice; both new link:# targets resolve; no added line over 100 columns outside the assertion-markup convention; git diff --check clean.

Still open, deliberately: the nine-type Template Parameter restriction, pending #652 — where the history now shows the list to be an artifact of the pre-#552 oneof rather than a deliberate restriction. The new assertion also adds a tck-id with no TCK coverage yet.

@wes-johnson
wes-johnson merged commit 041d777 into eclipse-sparkplug:develop Nov 9, 2026
3 checks passed
@wes-johnson
wes-johnson deleted the 651 branch November 9, 2026 23:43
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.

3 participants