Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 7 additions & 59 deletions specification/src/main/asciidoc/chapters/Sparkplug_6_Payloads.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -221,44 +221,34 @@ message Payload {
Template template_value = 13;
PropertySet propertyset_value = 14;
PropertySetList propertysets_value = 15;
TypedValueExtension extension_value = 16;
}

message TypedValueExtension {
extensions 1 to max;
}

extensions 17 to max;
}

message Template {

message Parameter {
string name = 1;
TypedValue typed_value = 2;
extensions 3 to max;
}

string version = 1; // The version of the Template to prevent mismatches
repeated Metric metrics = 2; // Each metric includes a name, datatype, and optionally a value
repeated Parameter parameters = 3;
string template_ref = 4; // MUST be a reference to a template definition if this is an instance (i.e. the name of the template definition) - MUST be omitted for template definitions
bool is_definition = 5;
extensions 6 to max;
}

message Status {
uint64 code = 1; // Result code of a command invocation - 0 indicates success, any non-zero value indicates an error
string message = 2; // Optional human readable status/error description
extensions 3 to max;
}

message Command {
repeated Metric arguments = 1; // Input argument definitions (NBIRTH/DBIRTH) or supplied argument values (NCMD/DCMD) - omitted for commands that accept no inputs
repeated Metric results = 2; // Result/output argument definitions (NBIRTH/DBIRTH) or returned result values (NRESP/DRESP) - omitted for commands that return no outputs
string correlation_id = 3; // Set on an NCMD/DCMD request and echoed unchanged in the corresponding NRESP/DRESP response
Status status = 4; // Execution status - present in NRESP/DRESP responses, omitted in BIRTH definitions and CMD requests
extensions 5 to max;
}

message DataSet {
Expand All @@ -274,23 +264,18 @@ message Payload {
repeated double double_values = 6;
repeated bool boolean_values = 7;
repeated string string_values = 8;

extensions 9 to max;
}

repeated Column columns = 1;
extensions 2 to max;
}

message PropertySet {
repeated string keys = 1; // Names of the properties
repeated TypedValue values = 2; // The Property Values
extensions 3 to max;
}

message PropertySetList {
repeated PropertySet propertyset = 1;
extensions 2 to max;
}

message MetaData {
Expand All @@ -312,7 +297,6 @@ message Payload {
string engUnit = 9; // Engineering units

// Future expansion
extensions 10 to max;
}

message Metric {
Expand All @@ -332,7 +316,6 @@ message Payload {
TypedValue value = 13;
Command command = 14; // Command definition (BIRTH), invocation (CMD), or response (RESP) - present when datatype == Command instead of 'value'
MetricOperation operation = 15; // Only in NMMETA/DMMETA: ADD, UPDATE, or DELETE
extensions 16 to max;
}

message Header {
Expand All @@ -345,13 +328,11 @@ message Payload {
string source = 7; // Source for CMD and REBIRTH messages - the Host Application ID that sent the message
string uuid = 8; // UUID to track message type in terms of schema definitions
string compression_algorithm = 9; // Present only when the content section is compressed - names the algorithm used
extensions 10 to max; // For third party extensions
}

message Content {
repeated Metric metrics = 1; // Repeated forever - no limit in Google Protobufs
bytes body = 2; // To optionally bypass the whole definition above
extensions 3 to max; // For third party extensions
}

Header header = 1; // Always present and always uncompressed
Expand All @@ -360,8 +341,6 @@ message Payload {
Content content = 2; // The Content of this message, uncompressed
bytes compressed = 3; // The compressed bytes of a serialized Content
}

extensions 4 to max; // For third party extensions
}
----

Expand Down Expand Up @@ -3561,9 +3540,8 @@ Google Protocol Buffers defines for proto3, so the representation of 64-bit inte
values, bytes, and non-finite floating point values will be familiar, and a Protocol Buffers JSON
implementation produces those forms directly. That agreement is a convenience and not a normative
dependency. The Sparkplug schema uses Protocol Buffers edition 2023, that mapping is specified for
proto3, it does not define how extension fields are represented, and it is not a versioned
standard, so this specification states the rules itself rather than incorporating them by
reference.
proto3, and it is not a versioned standard, so this specification states the rules itself rather
than incorporating them by reference.

Non-normative comment: Agreement on the scalar forms does not mean a conformant encoder can be
assembled from library calls. The structural mappings reshape every Metric, so an implementation
Expand Down Expand Up @@ -3635,15 +3613,17 @@ by ignoring it.*#
Non-normative comment: The two cases look similar in a payload and are not the same thing. An
unrecognized field name means the payload carries something this version of the application does
not know about, such as a field added by a later revision of this specification or a third party
extension; ignoring it is what allows an older application to keep working. An unrecognized metric
specification; ignoring it is what allows an older application to keep working. An unrecognized
metric
means the application's view of what the Edge Node reports is out of date, which is a
synchronization problem and a reason to issue a Rebirth Request, not something to pass over.

Non-normative comment: The naming rule keeps a JSON payload visually identical to the field names
in the Protocol Buffers schema, so the two encodings can be read against one another and against
the component definitions above without a translation table. Ignoring unrecognized keys is the JSON
counterpart of the extension ranges reserved in the Protocol Buffers schema, and serves the same
purpose for third party extensions.
counterpart of the Protocol Buffers rule that an unknown field does not make a message
unparseable, and serves the same purpose: an application built against an earlier revision of this
specification keeps working when a later one adds a field.

[[payloads_json_scalar]]
==== Scalar Value Mapping
Expand Down Expand Up @@ -3733,38 +3713,6 @@ Non-normative comment: The rule is driven by the declared type of the field rath
magnitude of a particular value, so an encoder derives it from the schema alone and no value can
lose precision because of how large it happened to be.

[[payloads_json_extensions]]
==== Extension Fields

The Sparkplug Google Protocol Buffers schema reserves an extension range in most of its messages so
that a third party can add fields without colliding with future Sparkplug fields. The JSON encoding
represents those fields as well.

[tck-testable tck-id-payloads-json-extension-key]#[yellow-background]*[tck-id-payloads-json-extension-key] A
field carried in a message's extension range MUST be represented with a JSON object key that is the
fully qualified name of that extension enclosed in square brackets, for example
'[com.example.vendor_tag]'.*#

[tck-testable tck-id-payloads-json-extension-value]#[yellow-background]*[tck-id-payloads-json-extension-value] The
value of an extension field MUST be represented according to the same rules as any other field of
its type, as defined in the link:#payloads_json_scalar[Scalar Value Mapping] and
link:#payloads_json_structural[Structural Mappings] sections.*#

[tck-not-testable tck-id-payloads-json-extension-ignore]#[yellow-background]*[tck-id-payloads-json-extension-ignore] A
consuming application that does not recognize an extension MUST ignore it, as it ignores any other
unrecognized key, and MUST NOT treat the payload as malformed.*#

Non-normative comment: The bracketed form is the one Google Protocol Buffers JSON implementations
already use for extensions, so it is specified here rather than invented. It is stated normatively
because the Protocol Buffers JSON Mapping is defined for proto3, which has no extensions, and so
does not cover this case at all.

Non-normative comment: An extension does not survive a round trip through an application that does
not know it. In the Google Protocol Buffers encoding an unknown field is retained and re-emitted,
but in JSON an unrecognized key is not. A deployment that depends on extensions reaching a
consumer through an intermediary should confirm that the intermediary understands them, rather
than assuming they are carried through.

[[payloads_json_structural]]
==== Structural Mappings

Expand Down
Loading