Repository navigation
[#651] Describe TypedValue once instead of three divergent times - #653
Conversation
…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
left a comment
There was a problem hiding this comment.
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-typeand-datatype-valuenow 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
left a comment
There was a problem hiding this comment.
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
left a comment
There was a problem hiding this comment.
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:408logs 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.
|
Pushed 43480dd. All seven review comments across both passes are addressed and every thread is resolved. Second pass (43480dd)
First pass (22bad02)
Verification: build successful; broken-anchor (11) and tck-id-anomaly (7) baselines unchanged against develop; the new assertion id appears exactly twice; both new 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 |
Addresses #651, except for the part that depends on #652.
The problem
Since #429 the schema has carried a single reusable
Payload.TypedValue, consumed byMetric.value,PropertySet.valuesandTemplate.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:int32/int64uint32/uint64/float/double/bool/string/bytesDataSetTemplatePropertySet/PropertySetListValueArrayThe change
Adds a
payloads_c_typedvaluesection 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:
int32andint64. The correct field for anInt32orInt64metric was named nowhere in the Metric section.ValueArray, whilepayloads-array-value-arraynormatively requires a Metric with an array datatype to carry its elements inarray_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-typetck-id-payloads-metric-propertyvalue-type-typetck-id-payloads-template-parameter-value-typeThat described the pre-#552 messages, where
Metric,PropertyValueandTemplate.Parametereach carried their ownuint32 typefield. Since the oneofs were consolidated the datatype lives inTypedValueand is theDataTypeenumeration — 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
DataTypeenumeration, leaving the representation to the encoding in use.Two editorial fixes ride along: the PropertyValue bullet is renamed from
typetodatatype, matching the field it describes, andint64_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)
PropertySetandPropertySetList. Pointing at the fullTypedValueset made a Metric with datatypePropertySetconforming, which it was not before — a silent widening in a PR meant to change nothing normative. Nowtck-id-payloads-metric-datatype-not-propertysetin the Metric section, which is what the closing note says a context's restriction should do. It adds atck-idwith no TCK coverage yet.datatypein JSON was wrong:tck-id-payloads-json-enum-nameand-enum-acceptalready say it, inpayloads_json_scalar. All three assertions now point there, and that paragraph is removed from this description.-datatype-value-typeis 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.is_nullagreement rule and the JSON flattening, and the closing note carries an example.SendComplexDataTestthat still quoted the old wording are updated.Separately,
SendComplexDataTest:405logs the datatype assertion text againstID_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_typedvalueandpayloads_c_datatype_arrayboth verified to exist. Exactly one type enumeration remains in the chapter, in the new section. No added line exceeds 100 columns.