Protocol Translator Connector

Overview

The Protocol Translator connector decodes a payload from one structured format into a flat key-value map, optionally renames keys, then encodes the result into a different target format. It is the canonical bridge between industrial protocols and JSON-native downstream stages.

Connector Type: MeddleProtocolTranslator

Supported Formats

• flat-json — Plain key/value map ({ "temp": 25.5, "press": 101.3 })
• nested-json — Nested object; decoded by dot-flattening, encoded by dot-unflattening ({ "sensor": { "temp": 25.5 } } ↔ { "sensor.temp": 25.5 })
• sparkplugb — Eclipse Sparkplug B shape: a metrics array of { "name": "...", "value": ... } entries
• opcua-json — Per-node OPC-UA JSON: each top-level key maps to { "value": ..., "sourceTimestamp": ... }

sourceFormat and targetFormat must differ.

Configuration

{
  "type": "MeddleProtocolTranslator",
  "config": {
    "sourceFormat": "sparkplugb",
    "targetFormat": "flat-json",
    "keyMappings": {
      "Temperature/Zone1": "temperature_zone_1",
      "Pressure/Main":     "pressure_main"
    }
  }
}

The connector first decodes Sparkplug B metrics into { "Temperature/Zone1": 25.5, "Pressure/Main": 101.3 }, then renames keys according to keyMappings, then emits the flat JSON.

Configuration Parameters

• sourceFormat (required): One of flat-json, nested-json, sparkplugb, opcua-json
• targetFormat (required): One of flat-json, nested-json, sparkplugb, opcua-json (must differ from sourceFormat)
• keyMappings: Optional map of oldKey -> newKey. Keys not present in the map pass through unchanged.

Translation Pipeline

1. Decode — Source payload is normalised to a flat map[string]any.
   • flat-json copies the payload as-is
   • nested-json flattens nested objects with . as separator
   • sparkplugb extracts each metrics[i].value keyed by metrics[i].name
   • opcua-json extracts each top-level node’s value field
2. Rename — Apply keyMappings to rename keys.
3. Encode — Reshape the flat map into the target format.
   • flat-json writes the map directly
   • nested-json unflattens .-delimited keys into nested objects
   • sparkplugb wraps each key/value as { "name": k, "value": v } in a metrics array
   • opcua-json wraps each value as { "value": v, "sourceTimestamp": null }

Use Cases

1. Sparkplug B to flat JSON for ingestion into databases that expect simple keys
2. OPC-UA JSON to flat JSON to strip node metadata before alerting
3. Flat JSON to Sparkplug B when publishing to a Sparkplug-compliant MQTT broker
4. Nested JSON flattening for downstream connectors that expect a flat key space

Example: OPC-UA to Flat JSON

{
  "type": "MeddleProtocolTranslator",
  "config": {
    "sourceFormat": "opcua-json",
    "targetFormat": "flat-json"
  }
}

Input:

{
  "ns=2;s=Temp":  { "value": 25.5, "sourceTimestamp": "2025-01-01T12:00:00Z" },
  "ns=2;s=Press": { "value": 101.3, "sourceTimestamp": "2025-01-01T12:00:00Z" }
}

Output:

{
  "ns=2;s=Temp":  25.5,
  "ns=2;s=Press": 101.3
}

Example: Flat JSON to Nested JSON

{
  "type": "MeddleProtocolTranslator",
  "config": {
    "sourceFormat": "flat-json",
    "targetFormat": "nested-json",
    "keyMappings": {
      "temp": "sensor.temperature",
      "press": "sensor.pressure"
    }
  }
}

Input: { "temp": 25.5, "press": 101.3 }

Output: { "sensor": { "temperature": 25.5, "pressure": 101.3 } }

Best Practices

• Use keyMappings to align upstream tag names with downstream schema conventions in a single step
• Combine with Transform for value-level changes (formulas, type coercion) that go beyond key renaming
• Sparkplug B payloads must contain a metrics array of objects with name and value fields — validate upstream if the source is unreliable
• Round-tripping flat-json -> opcua-json -> flat-json is supported, but sourceTimestamp is set to null on encode

Related Connectors

• Transform - JSONPath, template, and static value extraction
• Reshape - Direct key renaming without format change
• File Format - CSV and XML parsing