From bd6729f8a2a97ba192133d2346456cab54c9a5e7 Mon Sep 17 00:00:00 2001
From: Andrea Cosentino <ancosen@gmail.com>
Date: Mon, 31 Aug 2026 10:02:21 +0200
Subject: [PATCH] Fix #462: document that replace-field-action only renames top
 level fields

The Kamelet delegates to org.apache.camel.component.kafka.transform.ReplaceField,
whose process() iterates the top level map only:

    for (Map.Entry<Object, Object> entry : body.entrySet()) {
        final String fieldName = (String) entry.getKey();
        if (filterNames(fieldName, enabledFields, disabledFields)) {
            final Object fieldValue = entry.getValue();
            updatedBody.put(renameOptional(fieldName, renamingMap), fieldValue);
        }
    }

Nested objects are carried across as opaque values and never descended into,
so naming a nested field is silently a no-op. Reproduced with the example
from the issue:

    renames=message:msg  {"message":{"Hola":"mundo"}} -> {"msg":{"Hola":"mundo"}}
    renames=Hola:Hi      {"message":{"Hola":"mundo"}} -> {"message":{"Hola":"mundo"}}

Supporting nested paths would be a change to camel-kafka, not to this
template, so this documents the actual contract instead of implying a
capability the Kamelet does not have. enabled and disabled filter on the
same top level keys and are worded to match.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 kamelets/replace-field-action.kamelet.yaml | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/kamelets/replace-field-action.kamelet.yaml b/kamelets/replace-field-action.kamelet.yaml
index 33c5208a9..ee03ff120 100644
--- a/kamelets/replace-field-action.kamelet.yaml
+++ b/kamelets/replace-field-action.kamelet.yaml
@@ -30,23 +30,28 @@ metadata:
 spec:
   definition:
     title: "Replace Field Action"
-    description: Replace field with a different key in the message in transit.
+    description: |-
+      Replace field with a different key in the message in transit.
+
+      Only top level fields are considered. Fields nested inside an object are passed through
+      untouched, so a rename that names a nested field has no effect.
     required:
       - renames
     properties:
       enabled:
         title: Enabled
-        description: Comma separated list of fields to be enabled
+        description: Comma separated list of top level fields to be enabled
         type: string
         default: "all"
       disabled:
         title: Disabled
-        description: Comma separated list of fields to be disabled
+        description: Comma separated list of top level fields to be disabled
         type: string
         default: "none"
       renames:
         title: Renames
-        description: Comma separated list of field with new value to be renamed
+        description: Comma separated list of field with new value to be renamed. Only top level
+          fields are renamed; naming a field nested inside an object has no effect.
         type: string
         example: "foo:bar,c1:c2"
     type: object