From 954fa7edfab60e367e2a58406cae522f5a862fd2 Mon Sep 17 00:00:00 2001 From: wes-johnson Date: Fri, 6 Nov 2026 22:40:45 +0000 Subject: [PATCH 1/4] [#651] Describe TypedValue once instead of three divergent 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-#429 oneof is the subject of #652, and the answer decides whether that section ends up carrying a restriction or a reference. --- .../chapters/Sparkplug_6_Payloads.adoc | 86 +++++++++++-------- 1 file changed, 52 insertions(+), 34 deletions(-) diff --git a/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc b/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc index 9fed1e33..b948a692 100644 --- a/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc +++ b/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc @@ -688,6 +688,52 @@ distinguish the first metric of the publish from the rest continue to apply. ** _body_ *** This is an array of bytes which can be used for any custom binary encoded data. +[[payloads_c_typedvalue]] +==== TypedValue + +A Sparkplug TypedValue object carries a single value together with the datatype that describes it. +It is the one structure used wherever the specification carries a value: the value of a +link:#payloads_c_metric[Metric], the value of a property in a +link:#payloads_c_propertyset[PropertySet], and the value of a +link:#payloads_c_template_parameter[Template Parameter]. It includes the following components. + +* *datatype* +** This is the DataType of the value, as enumerated in the link:#payloads_c_datatypes[DataTypes] +section. It tells a consuming application how to interpret the value, and which of the fields below +carries it. +* *is_null* +** This is a Boolean flag which denotes whether the value is null. This is Sparkplug's mechanism of +explicitly denoting that a value is actually null, as distinct from a value that happens to be zero +or empty. +* *value* +** The value utilizes the 'oneof' mechanism of Google Protocol Buffers, so at most one of the +fields below is present. Which one is determined by the datatype. Note that if the is_null flag is +set to true the value can be omitted altogether. More information on the Google Protocol Buffer +types can be found here: https://developers.google.com/protocol-buffers/docs/proto#scalar +*** Google Protocol Buffer Type: _int32_ +*** Google Protocol Buffer Type: _int64_ +*** Google Protocol Buffer Type: _uint32_ +*** Google Protocol Buffer Type: _uint64_ +*** Google Protocol Buffer Type: _float_ +*** Google Protocol Buffer Type: _double_ +*** Google Protocol Buffer Type: _bool_ +*** Google Protocol Buffer Type: _string_ +*** Google Protocol Buffer Type: _bytes_ +*** Sparkplug _DataSet_ +**** Defined link:#payloads_c_dataset[here]. +*** Sparkplug _Template_ +**** Defined link:#payloads_c_template[here]. +*** Sparkplug _PropertySet_ +**** Defined link:#payloads_c_propertyset[here]. +*** Sparkplug _PropertySetList_ +**** Defined link:#payloads_c_propertysetlist[here]. +*** Sparkplug _ValueArray_ +**** Defined link:#payloads_c_datatype_array[here]. + +Non-normative comment: a context that uses a TypedValue may accept only part of this set. Where it +does, the restriction is stated in that context's own section rather than by restating the list +here, so that the permitted fields are described in exactly one place. + [[payloads_c_metric]] ==== Metric @@ -801,21 +847,9 @@ This is covered in the link:#payloads_c_metadata[metadata section]. metadata associated with a metric. This is covered in the link:#payloads_c_propertyset[property set section]. * *value* -** The value of a metric utilizes the ‘oneof’ mechanism of Google Protocol Buffers. The value -supplied with a metric MUST be one of the following types. Note if the metrics is_null flag is set -to true the value can be omitted altogether. More information on the Google Protocol Buffer types -can be found here: https://developers.google.com/protocol-buffers/docs/proto#scalar -*** Google Protocol Buffer Type: _uint32_ -*** Google Protocol Buffer Type: _uint64_ -*** Google Protocol Buffer Type: _float_ -*** Google Protocol Buffer Type: _double_ -*** Google Protocol Buffer Type: _bool_ -*** Google Protocol Buffer Type: _string_ -*** Google Protocol Buffer Type: _bytes_ -*** Sparkplug _DataSet_ -**** Defined link:#payloads_c_dataset[here]. -*** Sparkplug _Template_ -**** Defined link:#payloads_c_template[here]. +** This is a TypedValue carrying the metric's value, as described in the +link:#payloads_c_typedvalue[TypedValue section]. Which field carries the value is determined by the +metric's datatype, and the value may be omitted altogether if the is_null flag is set to true. [[payloads_c_quality]] ==== Quality @@ -982,25 +1016,9 @@ MUST be included in Property Value Definitions in NBIRTH and DBIRTH messages.*# ** This is a Boolean flag which denotes whether this property has a null value. This is Sparkplug B’s mechanism of explicitly denoting a property’s value is actually null. * *value* -** The value of a property utilizes the ‘oneof’ mechanism of Google Protocol Buffers. The value -supplied with a metric MUST be one of the following types. Note if the metrics is_null flag is set -to true the value can be omitted altogether. More information on the Google Protocol Buffer types -can be found here: https://developers.google.com/protocol-buffers/docs/proto#scalar -*** Google Protocol Buffer Type: _int32_ -*** Google Protocol Buffer Type: _int64_ -*** Google Protocol Buffer Type: _uint32_ -*** Google Protocol Buffer Type: _uint64_ -*** Google Protocol Buffer Type: _float_ -*** Google Protocol Buffer Type: _double_ -*** Google Protocol Buffer Type: _bool_ -*** Google Protocol Buffer Type: _string_ -*** Google Protocol Buffer Type: _bytes_ -*** Sparkplug _DataSet_ -**** Defined link:#payloads_c_dataset[here]. -*** Sparkplug _PropertySet_ -**** Defined link:#payloads_c_propertyset[here]. -*** Sparkplug _PropertySetList_ -**** Defined link:#payloads_c_propertysetlist[here]. +** This is a TypedValue carrying the property's value, as described in the +link:#payloads_c_typedvalue[TypedValue section]. Which field carries the value is determined by the +property's datatype, and the value may be omitted altogether if the is_null flag is set to true. [[payloads_c_well_known_properties]] ==== Well Known Properties From 03b769f39fae629b597c3f3e59ed021d47edd911 Mon Sep 17 00:00:00 2001 From: wes-johnson Date: Fri, 6 Nov 2026 23:04:03 +0000 Subject: [PATCH 2/4] [#651] Stop describing datatype as an unsigned 32-bit integer Three assertions said the datatype MUST be an unsigned 32-bit integer. 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 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 #652. --- .../main/asciidoc/chapters/Sparkplug_6_Payloads.adoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc b/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc index b948a692..ffb91979 100644 --- a/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc +++ b/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc @@ -804,7 +804,7 @@ written to on the Host Application for NCMD and DCMD messages. timestamp MUST be in UTC if it is included.*# * *datatype* ** [tck-testable tck-id-payloads-metric-datatype-value-type]#[yellow-background]*[tck-id-payloads-metric-datatype-value-type] The -datatype MUST be an unsigned 32-bit integer representing the datatype.*# +datatype MUST be a value of the DataType enumeration, represented as the encoding in use defines.*# ** [tck-testable tck-id-payloads-metric-datatype-value]#[yellow-background]*[tck-id-payloads-metric-datatype-value] The datatype MUST be one of the enumerated values as shown in the link:#payloads_c_datatypes[valid Sparkplug Data Types].*# @@ -1002,9 +1002,9 @@ array of values in a PropertySet MUST contain the same number of items that are A Sparkplug B PropertyValue object is used to encode the value and datatype of the value of a property in a PropertySet. It includes the following components. -* *type* +* *datatype* ** [tck-testable tck-id-payloads-metric-propertyvalue-type-type]#[yellow-background]*[tck-id-payloads-metric-propertyvalue-type-type] This -MUST be an unsigned 32-bit integer representing the datatype.*# +MUST be a value of the DataType enumeration, represented as the encoding in use defines.*# ** [tck-testable tck-id-payloads-metric-propertyvalue-type-value]#[yellow-background]*[tck-id-payloads-metric-propertyvalue-type-value] This value MUST be one of the enumerated values as shown in the link:#payloads_c_datatype_basic[Sparkplug Basic Data Types] @@ -1517,7 +1517,7 @@ MUST be included in every Template Parameter definition.*# MUST be a UTF-8 string representing the name of the Template parameter.*# * *type* ** [tck-testable tck-id-payloads-template-parameter-value-type]#[yellow-background]*[tck-id-payloads-template-parameter-value-type] This -MUST be an unsigned 32-bit integer representing the datatype.*# +MUST be a value of the DataType enumeration, represented as the encoding in use defines.*# ** [tck-testable tck-id-payloads-template-parameter-type-value]#[yellow-background]*[tck-id-payloads-template-parameter-type-value] This value MUST be one of the enumerated values as shown in the link:#payloads_c_datatype_basic[Sparkplug Basic Data Types].*# @@ -1529,8 +1529,8 @@ parameter values, not parameter definitions. * *value* ** The value of a template parameter utilizes the ‘oneof’ mechanism of Google Protocol Buffers. ** [tck-testable tck-id-payloads-template-parameter-value]#[yellow-background]*[tck-id-payloads-template-parameter-value] The -value supplied MUST be one of the following Google Protocol Buffer types: _int32_, int64_, _uint32_, -_uint64_, _float_, _double_, _bool_, _string_, or _bytes_.*# +value supplied MUST be one of the following Google Protocol Buffer types: _int32_, _int64_, +_uint32_, _uint64_, _float_, _double_, _bool_, _string_, or _bytes_.*# *** More information on these types can be found here: https://developers.google.com/protocol-buffers/docs/proto#scalar ** For a template definition, this is the default value of the parameter. For a template instance, From 22bad0209750071f40e7152e3bb9f39995552a85 Mon Sep 17 00:00:00 2001 From: wes-johnson Date: Sat, 7 Nov 2026 01:05:39 +0000 Subject: [PATCH 3/4] [#651] Review fixes: restore the Metric PropertySet restriction Addresses the review on #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. --- .../chapters/Sparkplug_6_Payloads.adoc | 21 ++++++++++++++----- .../tck/test/edge/SendComplexDataTest.java | 9 +++++--- 2 files changed, 22 insertions(+), 8 deletions(-) diff --git a/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc b/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc index ffb91979..bb8bf645 100644 --- a/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc +++ b/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc @@ -730,9 +730,14 @@ types can be found here: https://developers.google.com/protocol-buffers/docs/pro *** Sparkplug _ValueArray_ **** Defined link:#payloads_c_datatype_array[here]. +Where the enclosing object also carries a datatype and an is_null of its own, as a Metric does, the +two MUST agree; this is stated in the link:#payloads_json_typed_values[Typed Values] section, which +also describes how the JSON encoding represents some TypedValues without the nesting. + Non-normative comment: a context that uses a TypedValue may accept only part of this set. Where it -does, the restriction is stated in that context's own section rather than by restating the list -here, so that the permitted fields are described in exactly one place. +does, the restriction is stated in that context's own section rather than restated here, so that +the permitted fields are described in exactly one place. For example, a context that accepts only +scalar values says so in its own section, without repeating this list. [[payloads_c_metric]] ==== Metric @@ -804,10 +809,14 @@ written to on the Host Application for NCMD and DCMD messages. timestamp MUST be in UTC if it is included.*# * *datatype* ** [tck-testable tck-id-payloads-metric-datatype-value-type]#[yellow-background]*[tck-id-payloads-metric-datatype-value-type] The -datatype MUST be a value of the DataType enumeration, represented as the encoding in use defines.*# +datatype MUST be carried as a value of the DataType enumeration, represented as the encoding in +use defines (for JSON, see link:#payloads_json_scalar[Scalar Value Mapping]).*# ** [tck-testable tck-id-payloads-metric-datatype-value]#[yellow-background]*[tck-id-payloads-metric-datatype-value] The datatype MUST be one of the enumerated values as shown in the link:#payloads_c_datatypes[valid Sparkplug Data Types].*# +** [tck-testable tck-id-payloads-metric-datatype-not-propertyset]#[yellow-background]*[tck-id-payloads-metric-datatype-not-propertyset] The +datatype MUST NOT be PropertySet or PropertySetList, which are value types for a property rather +than for a metric. A metric's properties are carried in its properties field.*# ** [tck-testable tck-id-payloads-metric-datatype-req]#[yellow-background]*[tck-id-payloads-metric-datatype-req] The datatype MUST be included with each metric definition in NBIRTH and DBIRTH messages.*# ** [tck-testable tck-id-payloads-metric-datatype-not-req]#[yellow-background]*[tck-id-payloads-metric-datatype-not-req] The @@ -1004,7 +1013,8 @@ property in a PropertySet. It includes the following components. * *datatype* ** [tck-testable tck-id-payloads-metric-propertyvalue-type-type]#[yellow-background]*[tck-id-payloads-metric-propertyvalue-type-type] This -MUST be a value of the DataType enumeration, represented as the encoding in use defines.*# +MUST be a value of the DataType enumeration, represented as the encoding in use defines (for +JSON, see link:#payloads_json_scalar[Scalar Value Mapping]).*# ** [tck-testable tck-id-payloads-metric-propertyvalue-type-value]#[yellow-background]*[tck-id-payloads-metric-propertyvalue-type-value] This value MUST be one of the enumerated values as shown in the link:#payloads_c_datatype_basic[Sparkplug Basic Data Types] @@ -1517,7 +1527,8 @@ MUST be included in every Template Parameter definition.*# MUST be a UTF-8 string representing the name of the Template parameter.*# * *type* ** [tck-testable tck-id-payloads-template-parameter-value-type]#[yellow-background]*[tck-id-payloads-template-parameter-value-type] This -MUST be a value of the DataType enumeration, represented as the encoding in use defines.*# +MUST be a value of the DataType enumeration, represented as the encoding in use defines (for +JSON, see link:#payloads_json_scalar[Scalar Value Mapping]).*# ** [tck-testable tck-id-payloads-template-parameter-type-value]#[yellow-background]*[tck-id-payloads-template-parameter-type-value] This value MUST be one of the enumerated values as shown in the link:#payloads_c_datatype_basic[Sparkplug Basic Data Types].*# diff --git a/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SendComplexDataTest.java b/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SendComplexDataTest.java index 25daf6b8..94e5f983 100644 --- a/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SendComplexDataTest.java +++ b/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SendComplexDataTest.java @@ -352,7 +352,8 @@ public void checkDatatypeValidType(final @NotNull PublishPacket packet) { boolean isValid_DataType = true; boolean isValid_DataTypeValue = true; - logger.debug("Check Req: {} The datatype MUST be an unsigned 32-bit integer representing the datatype.", + logger.debug( + "Check Req: {} The datatype MUST be carried as a value of the DataType enumeration, represented as the encoding in use defines (for JSON, see Scalar Value Mapping).", ID_PAYLOADS_METRIC_DATATYPE_VALUE_TYPE); PayloadOrBuilder result = Utils.getSparkplugPayload(packet); @@ -402,7 +403,8 @@ public void checkPropertiesValidType(final @NotNull PublishPacket packet, String boolean isValid_PropertyValueTypeValue = true; boolean isValid_PropertyValueTypeReq = true; - logger.debug("Check Req: {} The datatype MUST be an unsigned 32-bit integer representing the datatype.", + logger.debug( + "Check Req: {} The datatype MUST be carried as a value of the DataType enumeration, represented as the encoding in use defines (for JSON, see Scalar Value Mapping).", ID_PAYLOADS_PROPERTYSET_KEYS_ARRAY_SIZE); PayloadOrBuilder result = Utils.getSparkplugPayload(packet); @@ -420,7 +422,8 @@ public void checkPropertiesValidType(final @NotNull PublishPacket packet, String "Check Req: {} The array of values in a PropertySet MUST contain the same number of items that are in the keys array.", PAYLOADS_PROPERTYSET_VALUES_ARRAY_SIZE); - logger.debug("Check Req: {} This MUST be an unsigned 32-bit integer representing the datatype.", + logger.debug( + "Check Req: {} This MUST be a value of the DataType enumeration, represented as the encoding in use defines (for JSON, see Scalar Value Mapping).", ID_PAYLOADS_METRIC_PROPERTYVALUE_TYPE_TYPE); logger.debug( "Check Req: {} This value MUST be one of the enumerated values as shown in the Sparkplug Basic Data Types or the Sparkplug Property Value Data Types.", From 43480dd876de9a8ac9863a07bcd5c7edb017e85c Mon Sep 17 00:00:00 2001 From: wes-johnson Date: Mon, 9 Nov 2026 23:20:23 +0000 Subject: [PATCH 4/4] [#651] Review fixes: drop an untagged MUST and a mismatched 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. --- .../src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc | 5 +++-- .../eclipse/sparkplug/tck/test/edge/SendComplexDataTest.java | 4 ---- 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc b/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc index bb8bf645..af08d3c6 100644 --- a/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc +++ b/specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc @@ -731,8 +731,9 @@ types can be found here: https://developers.google.com/protocol-buffers/docs/pro **** Defined link:#payloads_c_datatype_array[here]. Where the enclosing object also carries a datatype and an is_null of its own, as a Metric does, the -two MUST agree; this is stated in the link:#payloads_json_typed_values[Typed Values] section, which -also describes how the JSON encoding represents some TypedValues without the nesting. +two are required to agree; see the link:#payloads_json_typed_values[Typed Values] section, which +carries that requirement and also describes how the JSON encoding represents some TypedValues +without the nesting. Non-normative comment: a context that uses a TypedValue may accept only part of this set. Where it does, the restriction is stated in that context's own section rather than restated here, so that diff --git a/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SendComplexDataTest.java b/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SendComplexDataTest.java index 94e5f983..42225df5 100644 --- a/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SendComplexDataTest.java +++ b/tck/src/main/java/org/eclipse/sparkplug/tck/test/edge/SendComplexDataTest.java @@ -403,10 +403,6 @@ public void checkPropertiesValidType(final @NotNull PublishPacket packet, String boolean isValid_PropertyValueTypeValue = true; boolean isValid_PropertyValueTypeReq = true; - logger.debug( - "Check Req: {} The datatype MUST be carried as a value of the DataType enumeration, represented as the encoding in use defines (for JSON, see Scalar Value Mapping).", - ID_PAYLOADS_PROPERTYSET_KEYS_ARRAY_SIZE); - PayloadOrBuilder result = Utils.getSparkplugPayload(packet); if (result == null) {