Skip to content

Template parameter value assertion conflicts with the TypedValue schema #652

Open

Description

@wes-johnson

tck-id-payloads-template-parameter-value in payloads_c_template_parameter reads:

The value supplied MUST be one of the following Google Protocol Buffer types: int32, int64_, uint32, uint64, float, double, bool, string, or bytes.

The schema says something different. Since #429 collapsed the per-message oneofs into one reusable structure, Template.Parameter is:

message Parameter {
    string     name        = 1;
    TypedValue typed_value = 2;
}

TypedValue admits fourteen arms, including DataSet, Template, PropertySet, PropertySetList and ValueArray. The assertion permits nine of them. So the schema accepts a template parameter the specification text forbids, and neither says which is authoritative.

This needs a decision rather than an edit, because both readings are defensible:

  1. The restriction is intended. Template parameters are substitution values for a definition, and allowing a parameter to carry a nested Template or a DataSet raises questions the spec does not currently answer — recursion depth, whether a parameterised definition can itself be parameterised. If so, the assertion stands and the schema is simply more permissive than the spec, as it is in other places.
  2. The restriction is an artifact. The nine types are exactly the scalar arms of the old pre-Make re-usable one-of value structure in protobuf to ease programming #429 Parameter oneof. The list may have survived the refactor unchanged simply because nobody revisited it, in which case a parameter should accept whatever TypedValue accepts, and an array-valued parameter in particular looks useful.

Reading 2 looks more likely on the evidence — the nine types match the old oneof exactly, and the assertion was not touched when the structure changed — but that is inference about intent, not something the history settles, so it is a working-group call.

What depends on it

  • Whether the TCK should reject a template parameter carrying a composite value. Nothing tests this today.
  • Whether payloads_c_template_parameter ends up carrying a restriction or just a reference to the single TypedValue list proposed in the companion issue.
  • Whether ValueArray is permitted for parameters, which was missed when arrays moved into TypedValue.

Once the decision is made, the fix is either rewording the assertion to reference TypedValue or keeping it and adding a note in the schema that the field is deliberately narrower than its type.

Activity

  1. added this to the M1 milestone on Nov 6, 2026
  2. self-assigned this
    on Nov 6, 2026
  3. wes-johnson commented on Nov 6, 2026

    @wes-johnson
    ContributorAuthor

    I said in the issue that reading 2 was inference about intent rather than something the history settles. The history does settle it. Tracing it:

    The nine types are a verbatim description of the old oneof. Before #552, Template.Parameter had its own oneof value:

    message Parameter {
        optional string name        = 1;
        optional uint32 type        = 2;
        oneof value {
            int32  int32_value  = 3;   int64  int64_value   = 4;
            uint32 uint32_value = 5;   uint64 uint64_value  = 6;
            float  float_value  = 7;   double double_value  = 8;
            bool   boolean_value = 9;  string string_value  = 10;
            bytes  bytes_value  = 11;
            ParameterValueExtension extension_value = 12;
        }
    }

    Nine scalar arms, plus the extension mechanism. The assertion lists exactly those nine.

    #552 never touched the prose. git log -S on the assertion key returns only two commits, both repo-wide formatting passes (2cff800 in 2021, 59a9b32 in 2022). The #429 refactor (e0aaf27, May 2025) collapsed the four oneofs into TypedValue and changed Parameter to carry a TypedValue, but left every word of the surrounding text as it was.

    The list was being maintained until then. #62 (740c1c2, March 2025) added signed integer support and updated this assertion from seven types to nine, so it was tracking the schema right up to the refactor two months later.

    So the sequence is: the list described the Parameter oneof accurately, #62 kept it accurate, #552 replaced the oneof without revisiting the prose, and it has described a message that no longer exists ever since. That is an artifact, not a design decision — reading 2.

    Unless the working group wants to introduce a restriction that was never deliberately there, the fix is to reword the assertion to reference TypedValue rather than enumerate, which is what #653 does for the Metric and PropertyValue sections. That would also permit an array-valued template parameter, which seems useful and which nothing in the spec argues against.

    Two smaller things in the same assertion, worth fixing whenever it is touched:

    • int64_ is missing its leading underscore, so it renders without italics. Introduced in 740c1c2 and still there.
    • The section is titled PropertyValue-style around type, but TypedValue's field is datatype and it is an enum, not a uint32. tck-id-payloads-metric-propertyvalue-type-type still says "MUST be an unsigned 32-bit integer representing the datatype", which has the same pedigree — accurate before [#429] Consolidated 'oneof value' constructs into a single TypedValue to be reused in the proto file #552, stale since. That one is a separate issue if you want it tracked; I have not filed it.
  4. added 2 commits that reference this issue on Nov 6, 2026
  5. wes-johnson commented on Nov 11, 2026

    @wes-johnson
    ContributorAuthor

    Digging into the remaining piece of #651 turned up something that narrows this question considerably. The section states the restriction twice, in two vocabularies, and they disagree.

    1. The two assertions contradict each other over bytes.

    • tck-id-payloads-template-parameter-type-value — the datatype MUST be one of the Sparkplug Basic Data Types (payloads_c_datatype_basic): Unknown, Int8/16/32/64, UInt8/16/32/64, Float, Double, Boolean, String, DateTime, Text.
    • tck-id-payloads-template-parameter-value — the value MUST be one of nine Protocol Buffer types: int32, int64, uint32, uint64, float, double, bool, string, bytes.

    Bytes (17) and File (18) are Additional Types, not Basic ones. They are the only datatypes that map to the bytes arm. So a parameter carrying bytes_value satisfies the second assertion while having no datatype it can legally declare under the first. bytes is permitted and unreachable at the same time.

    The other eight arms are exactly what the Basic Data Types map to, so apart from bytes the list is a restatement of the datatype restriction in protobuf vocabulary.

    2. The nine-type restriction has never been enforced.

    SendComplexDataTest.checkTemplate scores ID_PAYLOADS_TEMPLATE_PARAMETER_VALUE from Utils.hasValue(p), which returns true for any populated arm:

    // Any arm counts, including bytes, which the specification allows for a parameter
    return tv.getValueCase() != Payload.TypedValue.ValueCase.VALUE_NOT_SET;

    A parameter carrying a dataset_value or a template_value passes. What the TCK actually enforces is the datatype restriction, through isBasicType (0 <= datatype <= DataType.Text, which is 14, so Bytes and File are excluded) — and it scores both -value-type and -type-value from that one boolean, the same two-ids-one-requirement pattern Nathan flagged for Metric in #653.

    What this means for the decision

    The operative restriction, in both the specification and the TCK, is "the datatype MUST be a Basic Data Type". The nine-type list is redundant with it, wrong about bytes, and untested. It should go regardless of how the question below is answered, which removes most of what was blocking #651.

    That leaves a narrower and cleaner question for the working group: should a template parameter be restricted to the Basic Data Types at all? That restriction is coherent, enforced, and may well be deliberate — a parameter is a substitution value, and allowing a nested Template or DataSet raises recursion questions the specification does not answer. My earlier evidence about #552 argued the list was an artifact; it now looks more likely that the datatype restriction is the real intent and the protobuf list was the artifact that drifted.

    If the working group keeps the Basic Data Types restriction, #651 closes by deleting -value and pointing the section at the single TypedValue list with that restriction stated as a delta. If it lifts the restriction, both assertions go and the section becomes a plain reference.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

M1questionFurther information is requested

Type

No type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions