[source-mongodb-v2] Specfic UUID Handling

[lepagea01]

Summary

Currently, the MongoDB source connector (source-mongodb-v2) emits all BSON binary fields as base64 strings, regardless of BSON subtype. While this is safe in a general sense, it causes semantic loss and inconsistency for fields that actually represent UUIDs, specifically BSON binary subtypes:

• 03 = legacy UUID (non-RFC 4122)
• 04 = standard UUID (RFC 4122)

This behavior is problematic because it makes it impossible to recover the original UUID with full confidence once the data is synced to a destination. This can silently break downstream use cases such as:

• Record linkage and foreign key relationships
• Join conditions between collections or datasets
• Data quality checks and validation
• Analytical models that rely on UUID comparisons

---

Proposed Feature

Introduce a source-level configuration setting, for example:

"uuid_rendering": "string"  // or "base64" (default)

When set to "string", the connector would:

• Automatically detect BSON binary fields with subtype 03 or 04
• If the field is 16 bytes long, decode it into a valid UUID string
• Fallback to base64 for all other cases

This somewhat mirrors the decoding already applied to _id in IdType, but generalizes it to all fields in the document.

---

Reference in Code

In the MongoDbCdcEventUtils class, the current logic for binary fields is:

case BINARY -> o.put(fieldName, toByteArray(reader.readBinaryData()));

Suggested improved version, gated by the optional setting:

case BINARY -> o.set(fieldName, useUuidRendering
    ? toUuidOrBase64(reader.readBinaryData())
    : toBase64(reader.readBinaryData()));

Where toUuidOrBase64(...) would look like (not tested):

private static JsonNode toUuidOrBase64(final BsonBinary bin) {
  if (bin == null) return NullNode.getInstance();

  byte[] bytes = bin.getData();
  byte subtype = bin.getType();

  if (bytes.length == 16 && (subtype == BsonBinarySubType.UUID_STANDARD.getValue()
      || subtype == BsonBinarySubType.UUID_LEGACY.getValue())) {
    try {
      UUID uuid = UuidHelper.decodeBinaryToUuid(bytes, subtype, UuidRepresentation.STANDARD);
      return new TextNode(uuid.toString());
    } catch (Exception e) {
      // fallback to base64
    }
  }

  return new TextNode(Base64.getEncoder().encodeToString(bytes));
}

---

Benefits

• Preserves backward compatibility (base64 remains the default behavior)
• Allows UUIDs to be rendered as human-readable strings for downstream usage
• Prevents join mismatches between base64 and UUID string formats
• Keeps binary fields as scalars in JSON (i.e., no structural change)

---

Notes

This is proposed as a non-breaking, opt-in feature to avoid disrupting existing pipelines. Default behavior remains unchanged unless the "uuid_rendering" flag is explicitly enabled.