This is an automated email from the ASF dual-hosted git repository.

davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-kamelets.git


The following commit(s) were added to refs/heads/main by this push:
     new 928cfbba1 chore: describe the field, schema and data type actions for 
people and AI assistants (#3145)
928cfbba1 is described below

commit 928cfbba1e889ec8bfcb2e9b74617706febb3f51
Author: Claus Ibsen <[email protected]>
AuthorDate: Tue Nov 17 11:20:21 2026 +0100

    chore: describe the field, schema and data type actions for people and AI 
assistants (#3145)
    
    * chore: describe the field, schema and data type actions for people and AI 
assistants
    
    Rewrites the descriptions and options of 13 actions to the standard of
    docs/modules/ROOT/pages/documenting.adoc (#3140): the six field actions
    (drop, extract, hoist, insert, mask, replace), set-body-action, the Avro
    and Protobuf serialize and deserialize actions, data-type-action and
    resolve-pojo-schema-action. Each was run, on Camel 4.23 and 4.24, to check
    the kind of body that goes in and comes out (JSON text, parsed JSON, Avro
    or Protobuf bytes), what happens to a missing field, and which headers and
    message properties are read and set. The descriptions state what holds on
    the released 4.23.
    
    Co-Authored-By: Claude Opus 5.5 <[email protected]>
    
    * chore: escape a brace before a name in Kamelet descriptions
    
    The documentation page renders descriptions and partial pages as
    AsciiDoc, where {body} is an attribute reference that fails the
    documentation check: write $\{body}, as the Camel documentation does.
    
    Co-Authored-By: Claude Opus 5.5 <[email protected]>
    
    ---------
    
    Co-authored-by: Claude Opus 5.5 <[email protected]>
---
 kamelets/avro-deserialize-action.kamelet.yaml      | 15 +++++--
 kamelets/avro-serialize-action.kamelet.yaml        | 22 +++++++--
 kamelets/data-type-action.kamelet.yaml             | 24 ++++++++--
 kamelets/drop-field-action.kamelet.yaml            | 21 ++++++++-
 kamelets/extract-field-action.kamelet.yaml         | 36 ++++++++++++---
 kamelets/hoist-field-action.kamelet.yaml           | 25 ++++++++++-
 kamelets/insert-field-action.kamelet.yaml          | 24 ++++++++--
 kamelets/mask-field-action.kamelet.yaml            | 24 ++++++++--
 kamelets/protobuf-deserialize-action.kamelet.yaml  | 13 +++++-
 kamelets/protobuf-serialize-action.kamelet.yaml    | 20 ++++++++-
 kamelets/replace-field-action.kamelet.yaml         | 29 +++++++++---
 kamelets/resolve-pojo-schema-action.kamelet.yaml   | 30 ++++++++-----
 kamelets/set-body-action.kamelet.yaml              | 14 +++++-
 .../main/resources/META-INF/kamelets-index.json    | 52 +++++++++++-----------
 .../kamelets/avro-deserialize-action.kamelet.yaml  | 15 +++++--
 .../kamelets/avro-serialize-action.kamelet.yaml    | 22 +++++++--
 .../kamelets/data-type-action.kamelet.yaml         | 24 ++++++++--
 .../kamelets/drop-field-action.kamelet.yaml        | 21 ++++++++-
 .../kamelets/extract-field-action.kamelet.yaml     | 36 ++++++++++++---
 .../kamelets/hoist-field-action.kamelet.yaml       | 25 ++++++++++-
 .../kamelets/insert-field-action.kamelet.yaml      | 24 ++++++++--
 .../kamelets/mask-field-action.kamelet.yaml        | 24 ++++++++--
 .../protobuf-deserialize-action.kamelet.yaml       | 13 +++++-
 .../protobuf-serialize-action.kamelet.yaml         | 20 ++++++++-
 .../kamelets/replace-field-action.kamelet.yaml     | 29 +++++++++---
 .../resolve-pojo-schema-action.kamelet.yaml        | 30 ++++++++-----
 .../kamelets/set-body-action.kamelet.yaml          | 14 +++++-
 27 files changed, 526 insertions(+), 120 deletions(-)

diff --git a/kamelets/avro-deserialize-action.kamelet.yaml 
b/kamelets/avro-deserialize-action.kamelet.yaml
index f3e0157b7..a37968aab 100644
--- a/kamelets/avro-deserialize-action.kamelet.yaml
+++ b/kamelets/avro-deserialize-action.kamelet.yaml
@@ -31,17 +31,26 @@ metadata:
 spec:
   definition:
     title: "Avro Deserialize Action"
-    description: "Deserialize payload to Avro."
+    description: |-
+      Turns each message of Avro binary data back into a JSON object, using 
the Avro schema the data was written with.
+
+      Use it to read records that arrive in Avro, a compact binary format 
described by a schema, for example from a Kafka topic, and work on them as 
JSON. To turn JSON into Avro, use `avro-serialize-action`; for Protobuf, use 
`protobuf-deserialize-action`.
+
+      Input: Avro binary data, as bytes, without the schema in it, such as 
`avro-serialize-action` writes.
+
+      Output: the body is parsed JSON (a Jackson `JsonNode`) with one field 
for each field of the schema. The `Content-Type` header is removed. Put 
`json-serialize-action` after this action to get JSON text.
+
+      Good to know: Avro data does not say which schema it was written with, 
so the schema must be the one the writer used. When `schema` is not set, the 
schema found by an earlier `resolve-pojo-schema-action` is used.
     type: object
     properties:
       schema:
         title: Schema
-        description: The Avro schema to use during serialization (as 
single-line, using JSON format)
+        description: "The Avro schema the data was written with, as JSON text: 
a record with a name and a list of fields, each with a name and a type. When it 
is not set, the schema found by an earlier `resolve-pojo-schema-action` is 
used."
         type: string
         example: '{"type": "record", "namespace": "com.example", "name": 
"FullName", "fields": [{"name": "first", "type": "string"},{"name": "last", 
"type": "string"}]}'
       validate:
         title: Validate
-        description: Indicates if the content must be validated against the 
schema
+        description: Meant to turn the check of the content against the schema 
on or off. It has no effect.
         type: boolean
         default: true
   dependencies:
diff --git a/kamelets/avro-serialize-action.kamelet.yaml 
b/kamelets/avro-serialize-action.kamelet.yaml
index 2df6a9f20..b19fc2a0f 100644
--- a/kamelets/avro-serialize-action.kamelet.yaml
+++ b/kamelets/avro-serialize-action.kamelet.yaml
@@ -31,19 +31,35 @@ metadata:
 spec:
   definition:
     title: "Avro Serialize Action"
-    description: "Serialize payload to Avro."
+    description: |-
+      Turns each message, a JSON object, into Avro binary data that follows 
the Avro schema you give.
+
+      Use it to send records in Avro, a compact binary format described by a 
schema, to a system that expects it, such as a Kafka topic whose readers decode 
Avro. To turn Avro back into JSON, use `avro-deserialize-action`; for Protobuf, 
use `protobuf-serialize-action`.
+
+      Input: parsed JSON (a Map or a Jackson `JsonNode`) whose fields match 
the schema. JSON text fails: put `json-deserialize-action` before this action 
to parse it.
+
+      Output: the body is the Avro binary data, as bytes, and the 
`Content-Type` header is set to `application/avro`.
+
+      Good to know: the schema is not written into the data, so whoever reads 
it needs the same schema. A message fails when it lacks a field of the schema, 
has a field the schema does not know, or has a value of the wrong type. When 
`schema` is not set, the schema found by an earlier 
`resolve-pojo-schema-action` is used.
     type: object
     properties:
       schema:
         title: Schema
-        description: The Avro schema to use during serialization (as 
single-line, using JSON format)
+        description: "The Avro schema of the records, as JSON text: a record 
with a name and a list of fields, each with a name and a type. When it is not 
set, the schema found by an earlier `resolve-pojo-schema-action` is used."
         type: string
         example: '{"type": "record", "namespace": "com.example", "name": 
"FullName", "fields": [{"name": "first", "type": "string"},{"name": "last", 
"type": "string"}]}'
       validate:
         title: Validate
-        description: Indicates if the content must be validated against the 
schema
+        description: "Meant to turn the check of the content against the 
schema on or off. It has no effect: a message that does not match the schema 
always fails."
         type: boolean
         default: true
+  dataTypes:
+    out:
+      headers:
+        Content-Type:
+          title: Content Type
+          description: Always `application/avro`.
+          type: string
   dependencies:
   - "camel:kamelet"
   - "camel:jackson-avro"
diff --git a/kamelets/data-type-action.kamelet.yaml 
b/kamelets/data-type-action.kamelet.yaml
index 306aac065..af6b1794e 100644
--- a/kamelets/data-type-action.kamelet.yaml
+++ b/kamelets/data-type-action.kamelet.yaml
@@ -30,19 +30,37 @@ metadata:
 spec:
   definition:
     title: "Data Type Action"
-    description: Applies a given data type with respective data transformation.
+    description: |-
+      Converts the body of each message into the data type you name, such as 
plain text, bytes, JSON, Avro or Protobuf, and sets the `Content-Type` header 
to match.
+
+      Use it to give the next step the kind of body it needs, such as bytes 
for a sink that writes files, or to turn JSON into Avro binary data after 
`resolve-pojo-schema-action` has found the schema. A data type is a name for a 
kind of body together with the conversion into it; `camel catalog transformer` 
lists the names.
+
+      Input: `text-plain` and `application-octet-stream` take any text; 
`application-json` and `application-x-struct` take JSON text; `avro-binary` and 
`protobuf-binary` take a JSON object, as JSON text or a Jackson `JsonNode` but 
not a Map; `avro-x-struct` and `protobuf-x-struct` take Avro or Protobuf binary 
data.
+
+      Output: `text-plain` gives text (`Content-Type` `text/plain`); 
`application-octet-stream` bytes (`application/octet-stream`); 
`application-json` JSON text as bytes (`application/json`); the `x-struct` ones 
parsed JSON, a Jackson `JsonNode` (`application/x-struct`); `avro-binary` and 
`protobuf-binary` binary data (`avro/binary`, `protobuf/binary`). 
`application-cloudevents+json` wraps the body, under `data`, in a CloudEvents 
JSON envelope.
+
+      Good to know: a name that does not exist makes every message fail, and 
so do the Avro and Protobuf data types without a schema from an earlier 
`resolve-pojo-schema-action`. With `text-plain`, a Map becomes text such as 
`{id=1, name=Ann}`, not JSON.
     required:
       - format
     type: object
     properties:
       scheme:
         title: Component Scheme
-        description: The data type component scheme enables users to apply 
Camel component specific data type conversions.
+        description: The name of a system, as Camel names it, such as 
`aws2-s3`, to use the data type made for that system instead of the general 
one. With `aws2-s3` and the format `application-cloudevents`, the data type 
`aws2-s3:application-cloudevents` is used. Leave it empty for the general data 
types.
         type: string
+        example: aws2-s3
       format:
         title: Data Type Format
-        description: Defines the data type that is applied by this action. 
Apache Camel and the Kamelet catalog support different data types and performs 
automatic message conversion according to the given type.
+        description: The name of the data type to convert the body into, such 
as `text-plain`, `application-octet-stream`, `application-json`, 
`application-x-struct`, `avro-binary`, `avro-x-struct`, `protobuf-binary`, 
`protobuf-x-struct` or `application-cloudevents+json`. `camel catalog 
transformer` lists them all; for the names written `scheme:format`, such as 
`aws2-s3:application-cloudevents`, put the part before the colon in `scheme`.
         type: string
+        example: application-json
+  dataTypes:
+    out:
+      headers:
+        Content-Type:
+          title: Content Type
+          description: The kind of body the data type gives, such as 
`text/plain`, `application/json` or `avro/binary`.
+          type: string
   dependencies:
     - "camel:kamelet"
   template:
diff --git a/kamelets/drop-field-action.kamelet.yaml 
b/kamelets/drop-field-action.kamelet.yaml
index 96aa679ec..33a322e85 100644
--- a/kamelets/drop-field-action.kamelet.yaml
+++ b/kamelets/drop-field-action.kamelet.yaml
@@ -30,15 +30,32 @@ metadata:
 spec:
   definition:
     title: "Drop Field Action"
-    description: Removes a custom field by given name from the message in 
transit.
+    description: |-
+      Removes one field, chosen by its name, from each message that is a JSON 
object.
+
+      Use it to take out a field that the next system does not accept or 
should not see, such as an internal ID or a password. To remove several fields, 
or to keep only some, use `replace-field-action`; to keep the field but hide 
its value, use `mask-field-action`.
+
+      Input: a JSON object, as JSON text or as parsed JSON (a Map or a Jackson 
`JsonNode`). Only the fields at the top level of the object are looked at. A 
JSON array is passed on unchanged; a body that is not JSON fails.
+
+      Output: the same object without the field. When the `Content-Type` 
header is `application/json`, the body is JSON text again; otherwise it is 
parsed JSON (a Jackson `JsonNode`), which `json-serialize-action` turns into 
JSON text.
+
+      Good to know: a message without the field is passed on unchanged. A 
field of the same name inside a nested object is not removed.
     required:
       - field
     properties:
       field:
         title: Field
-        description: The name of the field to be removed
+        description: The name of the top-level field to remove from the JSON 
object.
         type: string
+        example: password
     type: object
+  dataTypes:
+    in:
+      headers:
+        Content-Type:
+          title: Content Type
+          description: When it is `application/json`, the body is read as JSON 
text and written back as JSON text. Otherwise the body comes out as parsed JSON.
+          type: string
   dependencies:
   - "camel:jackson"
   - "camel:kamelet"
diff --git a/kamelets/extract-field-action.kamelet.yaml 
b/kamelets/extract-field-action.kamelet.yaml
index 40b8f798e..ef246c637 100644
--- a/kamelets/extract-field-action.kamelet.yaml
+++ b/kamelets/extract-field-action.kamelet.yaml
@@ -30,35 +30,59 @@ metadata:
 spec:
   definition:
     title: "Extract Field Action"
-    description: Extract a field from the message body.
+    description: |-
+      Replaces the body of each message that is a JSON object with the value 
of one of its fields, or copies that value into a header.
+
+      Use it to keep only the part of a message you need, such as the 
`payload` of an event or the `email` of a customer, or, with `headerOutput`, to 
have that value in a header for a later step while the body stays as it is. To 
do the opposite, and wrap a body in a field, use `hoist-field-action`.
+
+      Input: a JSON object, as JSON text or as parsed JSON (a Map or a Jackson 
`JsonNode`). The field must be at the top level of the object. A JSON array, or 
a body that is not JSON, fails.
+
+      Output: the body is the value of the field. When the `Content-Type` 
header is `application/json`, it is JSON text, so a text value keeps its quotes 
(`"Ann"`) unless `trimField` is true; otherwise it is the value itself, such as 
the text `Ann`. When `headerOutput` is true, the value goes into the header 
`CamelKameletsExtractFieldName`, or the header named by `headerOutputName`, and 
the body is left as it was.
+
+      Good to know: when the object does not have the field, the body or the 
header is empty (the JSON text `null` when the `Content-Type` header is 
`application/json`); the message does not fail.
     required:
       - field
     properties:
       field:
         title: Field
-        description: The name of the field to extract
+        description: The name of the top-level field whose value to take.
         type: string
+        example: email
       headerOutput:
         title: Header Output
-        description: If enable the action will store the extracted field in an 
header named CamelKameletsExtractFieldName
+        description: If true, the value is put in a header, 
`CamelKameletsExtractFieldName` unless `headerOutputName` is set, and the body 
is left as it was. If false, the value replaces the body.
         type: boolean
         default: false
       headerOutputName:
         title: Header Output Name
-        description: A custom name for the header containing the extracted 
field
+        description: The name of the header to put the value in. Only used 
when `headerOutput` is true. The default, `none`, means the header 
`CamelKameletsExtractFieldName`.
         default: "none"
         type: string
+        example: customerEmail
       strictHeaderCheck:
         title: Strict Header Check
-        description: If enabled the action will check if the header output 
name (custom or default) has been used already in the exchange. If so, the 
extracted field is stored in the message body, if not, the extracted field is 
stored in the selected header (custom or default).
+        description: Only used when `headerOutput` is true. If true, and the 
message already has the header, the header keeps its old value and the value of 
the field replaces the body instead.
         type: boolean
         default: false
       trimField:
         title: Trim Field
-        description: If enabled we return the Raw extracted field
+        description: If true, the body is the plain value, such as `Ann`, 
instead of JSON text such as `"Ann"`. It changes something only when the 
`Content-Type` header is `application/json`, and that header is then left as it 
is.
         type: boolean
         default: false
     type: object
+  dataTypes:
+    in:
+      headers:
+        Content-Type:
+          title: Content Type
+          description: When it is `application/json`, the body is read as JSON 
text and the value is written as JSON text, unless `trimField` is true.
+          type: string
+    out:
+      headers:
+        CamelKameletsExtractFieldName:
+          title: Extracted Field
+          description: The value of the field, when `headerOutput` is true and 
`headerOutputName` is not set.
+          type: string
   dependencies:
   - "camel:kamelet"
   - "camel:jackson"
diff --git a/kamelets/hoist-field-action.kamelet.yaml 
b/kamelets/hoist-field-action.kamelet.yaml
index 184c5dedc..669416cce 100644
--- a/kamelets/hoist-field-action.kamelet.yaml
+++ b/kamelets/hoist-field-action.kamelet.yaml
@@ -30,15 +30,36 @@ metadata:
 spec:
   definition:
     title: "Hoist Field Action"
-    description: "Wrap data in a single field."
+    description: |-
+      Wraps the body of each message in a new JSON object, as the value of the 
one field you name.
+
+      Use it to nest the whole message under one name, for example to turn 
`{"id":1}` into `{"order":{"id":1}}` for a system that expects that shape. To 
do the opposite, and take the value out of a field, use `extract-field-action`.
+
+      Input: any body. JSON is nested as a JSON object or array when it is 
parsed JSON (a Map or a Jackson `JsonNode`), or JSON text with the 
`Content-Type` header `application/json`. Any other text, including JSON text 
with another `Content-Type`, becomes a text value: `hello` gives 
`{"order":"hello"}`.
+
+      Output: the body is the new JSON object, as JSON text, and the 
`Content-Type` header is set to `application/json`.
     required:
       - field
     properties:
       field:
         title: Field
-        description: The name of the field that will contain the event.
+        description: The name of the field that holds the body in the new JSON 
object.
         type: string
+        example: order
     type: object
+  dataTypes:
+    in:
+      headers:
+        Content-Type:
+          title: Content Type
+          description: When it is `application/json`, JSON text in the body is 
nested as JSON. Otherwise text is nested as a text value.
+          type: string
+    out:
+      headers:
+        Content-Type:
+          title: Content Type
+          description: Always `application/json`.
+          type: string
   dependencies:
   - "camel:jackson"
   - "camel:kamelet"
diff --git a/kamelets/insert-field-action.kamelet.yaml 
b/kamelets/insert-field-action.kamelet.yaml
index 5d82f6246..1dac2646c 100644
--- a/kamelets/insert-field-action.kamelet.yaml
+++ b/kamelets/insert-field-action.kamelet.yaml
@@ -30,20 +30,38 @@ metadata:
 spec:
   definition:
     title: "Insert Field Action"
-    description: Adds a custom field with a simple language parsed value to 
the message in transit.
+    description: |-
+      Adds a field with a value you choose to each message that is a JSON 
object, or replaces the value when the field is already there.
+
+      Use it to tag records with where they come from or which environment 
they passed through, or to add a value from a header or the current date. To 
add a header instead of a field, use `insert-header-action`.
+
+      Input: a JSON object, as JSON text or as parsed JSON (a Map or a Jackson 
`JsonNode`). When the body is a JSON array, the value is added at the end of 
the array and `field` is not used. A body that is not JSON fails.
+
+      Output: the object with the field. When the `Content-Type` header is 
`application/json`, the body is JSON text again; otherwise it is parsed JSON (a 
Jackson `JsonNode`), which `json-serialize-action` turns into JSON text.
+
+      Good to know: the value is always added as a JSON text value, in quotes, 
even when it looks like a number. The field is added at the top level of the 
object.
     required:
       - field
       - value
     properties:
       field:
         title: Field
-        description: The name of the field to be added.
+        description: The name of the top-level field to add. When the object 
already has a field of this name, its value is replaced.
         type: string
+        example: source
       value:
         title: Value
-        description: The value of the field.
+        description: "The value of the new field, as text. It can include 
values from the message: `${header.name}` is the value of a header, 
`${date:now:yyyy-MM-dd}` the current date."
         type: string
+        example: "shop-${header.region}"
     type: object
+  dataTypes:
+    in:
+      headers:
+        Content-Type:
+          title: Content Type
+          description: When it is `application/json`, the body is read as JSON 
text and written back as JSON text. Otherwise the body comes out as parsed JSON.
+          type: string
   dependencies:
   - "camel:jackson"
   - "camel:kamelet"
diff --git a/kamelets/mask-field-action.kamelet.yaml 
b/kamelets/mask-field-action.kamelet.yaml
index ef8666dce..03685ae2f 100644
--- a/kamelets/mask-field-action.kamelet.yaml
+++ b/kamelets/mask-field-action.kamelet.yaml
@@ -30,20 +30,38 @@ metadata:
 spec:
   definition:
     title: "Mask Fields Action"
-    description: "Mask fields with a constant value in the message in transit."
+    description: |-
+      Replaces the values of the fields you name in each message that is a 
JSON object with a fixed value, such as `XXXX`.
+
+      Use it to hide card numbers, passwords or personal data before the 
messages are logged or sent to another system. To remove a field entirely, use 
`drop-field-action`, or `replace-field-action` for several fields.
+
+      Input: a JSON object, as JSON text or as parsed JSON (a Map or a Jackson 
`JsonNode`). Only the fields at the top level of the object are masked; nested 
objects are left as they are. A JSON array, or a body that is not JSON, fails.
+
+      Output: the object with the masked values; the order of its fields can 
change. When the `Content-Type` header is `application/json`, the body is JSON 
text again; otherwise it is parsed JSON (a Jackson `JsonNode`), which 
`json-serialize-action` turns into JSON text.
+
+      Good to know: the replacement must suit the value it replaces. A text 
value takes any replacement, but a number takes only a number, such as `0`, and 
a true or false value, an object or a list cannot be masked: such a message 
fails. A named field that the object does not have is ignored.
     required:
       - fields
       - replacement
     properties:
       fields:
         title: Fields
-        description: Comma separated list of fields to mask
+        description: The names of the top-level fields to mask, separated by 
commas.
         type: string
+        example: "card,password"
       replacement:
         title: Replacement
-        description: Replacement for the fields to be masked
+        description: The value that replaces the value of each masked field. 
Any text works for a text value; a number value needs a number, such as `0`.
         type: string
+        example: "****"
     type: object
+  dataTypes:
+    in:
+      headers:
+        Content-Type:
+          title: Content Type
+          description: When it is `application/json`, the body is read as JSON 
text and written back as JSON text. Otherwise the body comes out as parsed JSON.
+          type: string
   dependencies:
   - "camel:jackson"
   - "camel:kamelet"
diff --git a/kamelets/protobuf-deserialize-action.kamelet.yaml 
b/kamelets/protobuf-deserialize-action.kamelet.yaml
index dca9bdf2d..33bf21f85 100644
--- a/kamelets/protobuf-deserialize-action.kamelet.yaml
+++ b/kamelets/protobuf-deserialize-action.kamelet.yaml
@@ -30,12 +30,21 @@ metadata:
 spec:
   definition:
     title: "Protobuf Deserialize Action"
-    description: "Deserialize payload to Protobuf."
+    description: |-
+      Turns each message of Protobuf binary data back into a JSON object, 
using the Protobuf schema the data was written with.
+
+      Use it to read records that arrive in Protocol Buffers (Protobuf), a 
compact binary format described by a schema, and work on them as JSON. To turn 
JSON into Protobuf, use `protobuf-serialize-action`; for Avro, use 
`avro-deserialize-action`.
+
+      Input: Protobuf binary data, as bytes, such as 
`protobuf-serialize-action` writes.
+
+      Output: the body is parsed JSON (a Jackson `JsonNode`) with the fields 
found in the data. The `Content-Type` header is removed. Put 
`json-serialize-action` after this action to get JSON text.
+
+      Good to know: a body that is not Protobuf data, such as JSON text, 
fails. When `schema` is not set, the schema found by an earlier 
`resolve-pojo-schema-action` is used.
     type: object
     properties:
       schema:
         title: Schema
-        description: The Protobuf schema to use during serialization (as 
single-line)
+        description: "The Protobuf schema the data was written with, in the 
`.proto` language: a `message` with its fields, each with a type, a name and a 
number. When it is not set, the schema found by an earlier 
`resolve-pojo-schema-action` is used."
         type: string
         example: 'message Person { required string first = 1; required string 
last = 2; }'
   dependencies:
diff --git a/kamelets/protobuf-serialize-action.kamelet.yaml 
b/kamelets/protobuf-serialize-action.kamelet.yaml
index 3e72f106a..1f88100f3 100644
--- a/kamelets/protobuf-serialize-action.kamelet.yaml
+++ b/kamelets/protobuf-serialize-action.kamelet.yaml
@@ -30,14 +30,30 @@ metadata:
 spec:
   definition:
     title: "Protobuf Serialize Action"
-    description: "Serialize payload to Protobuf."
+    description: |-
+      Turns each message, a JSON object, into Protobuf binary data that 
follows the Protobuf schema you give.
+
+      Use it to send records in Protocol Buffers (Protobuf), a compact binary 
format described by a schema, to a system that expects it, such as a Kafka 
topic whose readers decode Protobuf. To turn Protobuf back into JSON, use 
`protobuf-deserialize-action`; for Avro, use `avro-serialize-action`.
+
+      Input: parsed JSON (a Map or a Jackson `JsonNode`) whose fields match 
the schema. Put `json-deserialize-action` before this action when the body is 
JSON text.
+
+      Output: the body is the Protobuf binary data, as bytes, and the 
`Content-Type` header is set to `application/protobuf`.
+
+      Good to know: JSON text is not turned into Protobuf: it is passed on as 
it is, yet the `Content-Type` header is set to `application/protobuf`. A 
message fails when it has a field the schema does not know or a value of the 
wrong type; a field of the schema that the message lacks is left out, even when 
it is marked `required`. When `schema` is not set, the schema found by an 
earlier `resolve-pojo-schema-action` is used.
     type: object
     properties:
       schema:
         title: Schema
-        description: The Protobuf schema to use during serialization (as 
single-line)
+        description: "The Protobuf schema of the records, in the `.proto` 
language: a `message` with its fields, each with a type, a name and a number. 
When it is not set, the schema found by an earlier `resolve-pojo-schema-action` 
is used."
         type: string
         example: 'message Person { required string first = 1; required string 
last = 2; }'
+  dataTypes:
+    out:
+      headers:
+        Content-Type:
+          title: Content Type
+          description: Always `application/protobuf`.
+          type: string
   dependencies:
   - "camel:kamelet"
   - "camel:jackson-protobuf"
diff --git a/kamelets/replace-field-action.kamelet.yaml 
b/kamelets/replace-field-action.kamelet.yaml
index a4f4b866a..44f39f241 100644
--- a/kamelets/replace-field-action.kamelet.yaml
+++ b/kamelets/replace-field-action.kamelet.yaml
@@ -30,27 +30,44 @@ metadata:
 spec:
   definition:
     title: "Replace Field Action"
-    description: Replace field with a different key in the message in transit.
+    description: |-
+      Renames fields of each message that is a JSON object, and can also keep 
only some fields or remove others.
+
+      Use it to match the field names another system expects, such as `name` 
to `fullName`, and to leave out the fields it should not get. To remove a 
single field, `drop-field-action` is simpler; to hide a value but keep the 
field, use `mask-field-action`.
+
+      Input: a JSON object, as JSON text or as parsed JSON (a Map or a Jackson 
`JsonNode`). Only the fields at the top level of the object are renamed, kept 
or removed; nested objects are left as they are. A JSON array, or a body that 
is not JSON, fails.
+
+      Output: the object with the renamed fields, without the removed ones; 
the order of its fields can change. When the `Content-Type` header is 
`application/json`, the body is JSON text again; otherwise it is parsed JSON (a 
Jackson `JsonNode`), which `json-serialize-action` turns into JSON text.
+
+      Good to know: `renames` is required, even when you only want to keep or 
remove fields. A rename of a field the object does not have is ignored. When 
`enabled` and `disabled` together would remove every field, the object is 
passed on unchanged.
     required:
       - renames
     properties:
       enabled:
         title: Enabled
-        description: Comma separated list of top level fields to be enabled
+        description: The names of the top-level fields to keep, separated by 
commas; all the other fields are removed. The default, `all`, keeps every field.
         type: string
         default: "all"
+        example: "id,name"
       disabled:
         title: Disabled
-        description: Comma separated list of top level fields to be disabled
+        description: The names of the top-level fields to remove, separated by 
commas. The default, `none`, removes nothing.
         type: string
         default: "none"
+        example: "card,password"
       renames:
         title: Renames
-        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.
+        description: The fields to rename, as `old:new` pairs separated by 
commas. Only top-level fields are renamed; naming a field nested inside an 
object has no effect. A pair without `:` makes every message fail.
         type: string
-        example: "foo:bar,c1:c2"
+        example: "name:fullName,zip:postalCode"
     type: object
+  dataTypes:
+    in:
+      headers:
+        Content-Type:
+          title: Content Type
+          description: When it is `application/json`, the body is read as JSON 
text and written back as JSON text. Otherwise the body comes out as parsed JSON.
+          type: string
   types:
     in:
       mediaType: application/json
diff --git a/kamelets/resolve-pojo-schema-action.kamelet.yaml 
b/kamelets/resolve-pojo-schema-action.kamelet.yaml
index 5e25eaf9f..6f64d949b 100644
--- a/kamelets/resolve-pojo-schema-action.kamelet.yaml
+++ b/kamelets/resolve-pojo-schema-action.kamelet.yaml
@@ -31,29 +31,39 @@ metadata:
 spec:
   definition:
     title: "Resolve Schema Action"
-    description: "Resolves schema from given mime type and payload. Sets the 
resolved schema, the schema type and its content class as properties for later 
reference."
+    description: |-
+      Attaches an Avro, Protobuf or JSON schema to each message, for the later 
steps that need one, and leaves the body unchanged.
+
+      Use it to give the schema once, before `data-type-action` with a format 
such as `avro-binary` or `protobuf-binary`, which takes its schema only from 
here. `avro-serialize-action`, `avro-deserialize-action`, 
`protobuf-serialize-action` and `protobuf-deserialize-action` use it too when 
their own `schema` is not set.
+
+      Input: any body. The schema comes from `schema`, or else from the Java 
class named by `contentClass`.
+
+      Output: the body and the headers are unchanged. The schema is kept with 
the message in the properties `X-Content-Schema` and `X-Content-Schema-Type` 
(`avsc`, `proto` or `json`), which are not headers and are not sent to other 
systems.
+
+      Good to know: with the default `mimeType`, `application/json`, and no 
`schema` or `contentClass`, it does nothing. A `mimeType` it does not know 
makes every message fail with "Unsupported type".
     type: object
     properties:
       mimeType:
-        title: Mime Type
-        description: The mime type to determine the schema resolver 
implementation that should perform the operation.
+        title: MIME Type
+        description: "Which kind of schema `schema` holds and later steps 
need: `avro/binary`, `application/avro` or `avro/x-struct` for Avro; 
`protobuf/binary`, `application/protobuf` or `protobuf/x-struct` for Protobuf; 
`application/json` or `application/x-struct` for JSON Schema. With 
`application/x-java-object`, the kind is taken from `targetMimeType`."
         type: string
         default: "application/json"
-        example: "application/json"
+        example: "avro/binary"
       schema:
         title: Schema
-        description: Optional schema content (as single-line, using JSON 
format).
+        description: "The schema itself: for Avro, JSON text such as the 
example; for Protobuf, a `message` in the `.proto` language; for JSON, a JSON 
Schema as JSON text. When it is not set, the schema is made from 
`contentClass`."
         type: string
+        example: '{"type": "record", "namespace": "com.example", "name": 
"FullName", "fields": [{"name": "first", "type": "string"},{"name": "last", 
"type": "string"}]}'
       contentClass:
         title: Content Class
-        description: Type information of the content object. Fully qualified 
class name.
+        description: The full name of a Java class in the application whose 
fields define the schema. Only used when `schema` is not set.
         type: string
-        example: "org.apache.camel.content.Foo"
+        example: "com.example.Order"
       targetMimeType:
-        title: Target Mime Type
-        description: Additional mime type information used to determine the 
schema resolver. Usually only used in combination with mime type 
"application/x-java-object"
+        title: Target MIME Type
+        description: The kind of schema to find, as in `mimeType`, such as 
`avro/binary`. Only used when `mimeType` is `application/x-java-object`.
         type: string
-        example: "application/json"
+        example: "avro/binary"
   dependencies:
     - "camel:kamelet"
     - "camel:jackson-avro"
diff --git a/kamelets/set-body-action.kamelet.yaml 
b/kamelets/set-body-action.kamelet.yaml
index 7bc125be2..cf9c3493a 100644
--- a/kamelets/set-body-action.kamelet.yaml
+++ b/kamelets/set-body-action.kamelet.yaml
@@ -31,14 +31,24 @@ metadata:
 spec:
   definition:
     title: "Set Body Action"
-    description: Sets a simple language parsed value as the new message body 
in transit.
+    description: |-
+      Replaces the body of each message with a text you write, which can 
include values from the message, such as a header.
+
+      Use it to send a fixed text or a small JSON document, such as a status 
message, or to build a short text from headers and the old body. For longer 
texts, a template Kamelet such as `mustache-template-action` is easier to 
maintain.
+
+      Input: any message. In the text, `$\{body}` is the old body and 
`${header.name}` the value of a header.
+
+      Output: the body is the text, with the values filled in. The headers are 
kept as they were, `Content-Type` too, so set it to match the new body when 
needed, for example with `insert-header-action`.
+
+      Good to know: up to Camel 4.23, two closing braces in a row are read as 
the end of a placeholder and make the Kamelet fail to start, so write nested 
JSON with a space between them, as `} }`.
     required:
       - value
     properties:
       value:
         title: Value
-        description: The value to set as new body
+        description: "The new body, as text. `$\\{body}` is replaced by the 
old body, `${header.name}` by the value of the header `name`, and 
`${date:now:yyyy-MM-dd}` by the current date."
         type: string
+        example: "Order ${header.orderId} received"
     type: object
   dependencies:
   - "camel:kamelet"
diff --git 
a/library/camel-kamelets/src/main/resources/META-INF/kamelets-index.json 
b/library/camel-kamelets/src/main/resources/META-INF/kamelets-index.json
index a44ff643d..d6b3ba45f 100644
--- a/library/camel-kamelets/src/main/resources/META-INF/kamelets-index.json
+++ b/library/camel-kamelets/src/main/resources/META-INF/kamelets-index.json
@@ -4,8 +4,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "Avro Deserialize Action",
-    "summary" : "Deserialize payload to Avro.",
-    "description" : "Deserialize payload to Avro.",
+    "summary" : "Turns each message of Avro binary data back into a JSON 
object, using the Avro schema the data was written with.",
+    "description" : "Turns each message of Avro binary data back into a JSON 
object, using the Avro schema the data was written with.\n\nUse it to read 
records that arrive in Avro, a compact binary format described by a schema, for 
example from a Kafka topic, and work on them as JSON. To turn JSON into Avro, 
use `avro-serialize-action`; for Protobuf, use 
`protobuf-deserialize-action`.\n\nInput: Avro binary data, as bytes, without 
the schema in it, such as `avro-serialize-action` writes.\ [...]
     "group" : "Actions",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
@@ -14,8 +14,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "Avro Serialize Action",
-    "summary" : "Serialize payload to Avro.",
-    "description" : "Serialize payload to Avro.",
+    "summary" : "Turns each message, a JSON object, into Avro binary data that 
follows the Avro schema you give.",
+    "description" : "Turns each message, a JSON object, into Avro binary data 
that follows the Avro schema you give.\n\nUse it to send records in Avro, a 
compact binary format described by a schema, to a system that expects it, such 
as a Kafka topic whose readers decode Avro. To turn Avro back into JSON, use 
`avro-deserialize-action`; for Protobuf, use 
`protobuf-serialize-action`.\n\nInput: parsed JSON (a Map or a Jackson 
`JsonNode`) whose fields match the schema. JSON text fails: put `j [...]
     "group" : "Actions",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
@@ -674,8 +674,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "Data Type Action",
-    "summary" : "Applies a given data type with respective data 
transformation.",
-    "description" : "Applies a given data type with respective data 
transformation.",
+    "summary" : "Converts the body of each message into the data type you 
name, such as plain text, bytes, JSON, Avro or Protobuf, and sets the 
`Content-Type` header to match.",
+    "description" : "Converts the body of each message into the data type you 
name, such as plain text, bytes, JSON, Avro or Protobuf, and sets the 
`Content-Type` header to match.\n\nUse it to give the next step the kind of 
body it needs, such as bytes for a sink that writes files, or to turn JSON into 
Avro binary data after `resolve-pojo-schema-action` has found the schema. A 
data type is a name for a kind of body together with the conversion into it; 
`camel catalog transformer` lists t [...]
     "group" : "Actions",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
@@ -764,8 +764,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "Drop Field Action",
-    "summary" : "Removes a custom field by given name from the message in 
transit.",
-    "description" : "Removes a custom field by given name from the message in 
transit.",
+    "summary" : "Removes one field, chosen by its name, from each message that 
is a JSON object.",
+    "description" : "Removes one field, chosen by its name, from each message 
that is a JSON object.\n\nUse it to take out a field that the next system does 
not accept or should not see, such as an internal ID or a password. To remove 
several fields, or to keep only some, use `replace-field-action`; to keep the 
field but hide its value, use `mask-field-action`.\n\nInput: a JSON object, as 
JSON text or as parsed JSON (a Map or a Jackson `JsonNode`). Only the fields at 
the top level of the [...]
     "group" : "Actions",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
@@ -854,8 +854,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "Extract Field Action",
-    "summary" : "Extract a field from the message body.",
-    "description" : "Extract a field from the message body.",
+    "summary" : "Replaces the body of each message that is a JSON object with 
the value of one of its fields, or copies that value into a header.",
+    "description" : "Replaces the body of each message that is a JSON object 
with the value of one of its fields, or copies that value into a header.\n\nUse 
it to keep only the part of a message you need, such as the `payload` of an 
event or the `email` of a customer, or, with `headerOutput`, to have that value 
in a header for a later step while the body stays as it is. To do the opposite, 
and wrap a body in a field, use `hoist-field-action`.\n\nInput: a JSON object, 
as JSON text or as p [...]
     "group" : "Actions",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
@@ -1144,8 +1144,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "Hoist Field Action",
-    "summary" : "Wrap data in a single field.",
-    "description" : "Wrap data in a single field.",
+    "summary" : "Wraps the body of each message in a new JSON object, as the 
value of the one field you name.",
+    "description" : "Wraps the body of each message in a new JSON object, as 
the value of the one field you name.\n\nUse it to nest the whole message under 
one name, for example to turn `{\"id\":1}` into `{\"order\":{\"id\":1}}` for a 
system that expects that shape. To do the opposite, and take the value out of a 
field, use `extract-field-action`.\n\nInput: any body. JSON is nested as a JSON 
object or array when it is parsed JSON (a Map or a Jackson `JsonNode`), or JSON 
text with the `Co [...]
     "group" : "Actions",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
@@ -1244,8 +1244,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "Insert Field Action",
-    "summary" : "Adds a custom field with a simple language parsed value to 
the message in transit.",
-    "description" : "Adds a custom field with a simple language parsed value 
to the message in transit.",
+    "summary" : "Adds a field with a value you choose to each message that is 
a JSON object, or replaces the value when the field is already there.",
+    "description" : "Adds a field with a value you choose to each message that 
is a JSON object, or replaces the value when the field is already there.\n\nUse 
it to tag records with where they come from or which environment they passed 
through, or to add a value from a header or the current date. To add a header 
instead of a field, use `insert-header-action`.\n\nInput: a JSON object, as 
JSON text or as parsed JSON (a Map or a Jackson `JsonNode`). When the body is a 
JSON array, the value  [...]
     "group" : "Actions",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
@@ -1734,8 +1734,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "Mask Fields Action",
-    "summary" : "Mask fields with a constant value in the message in transit.",
-    "description" : "Mask fields with a constant value in the message in 
transit.",
+    "summary" : "Replaces the values of the fields you name in each message 
that is a JSON object with a fixed value, such as `XXXX`.",
+    "description" : "Replaces the values of the fields you name in each 
message that is a JSON object with a fixed value, such as `XXXX`.\n\nUse it to 
hide card numbers, passwords or personal data before the messages are logged or 
sent to another system. To remove a field entirely, use `drop-field-action`, or 
`replace-field-action` for several fields.\n\nInput: a JSON object, as JSON 
text or as parsed JSON (a Map or a Jackson `JsonNode`). Only the fields at the 
top level of the object ar [...]
     "group" : "Actions",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
@@ -2034,8 +2034,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "Protobuf Deserialize Action",
-    "summary" : "Deserialize payload to Protobuf.",
-    "description" : "Deserialize payload to Protobuf.",
+    "summary" : "Turns each message of Protobuf binary data back into a JSON 
object, using the Protobuf schema the data was written with.",
+    "description" : "Turns each message of Protobuf binary data back into a 
JSON object, using the Protobuf schema the data was written with.\n\nUse it to 
read records that arrive in Protocol Buffers (Protobuf), a compact binary 
format described by a schema, and work on them as JSON. To turn JSON into 
Protobuf, use `protobuf-serialize-action`; for Avro, use 
`avro-deserialize-action`.\n\nInput: Protobuf binary data, as bytes, such as 
`protobuf-serialize-action` writes.\n\nOutput: the body [...]
     "group" : "Actions",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
@@ -2044,8 +2044,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "Protobuf Serialize Action",
-    "summary" : "Serialize payload to Protobuf.",
-    "description" : "Serialize payload to Protobuf.",
+    "summary" : "Turns each message, a JSON object, into Protobuf binary data 
that follows the Protobuf schema you give.",
+    "description" : "Turns each message, a JSON object, into Protobuf binary 
data that follows the Protobuf schema you give.\n\nUse it to send records in 
Protocol Buffers (Protobuf), a compact binary format described by a schema, to 
a system that expects it, such as a Kafka topic whose readers decode Protobuf. 
To turn Protobuf back into JSON, use `protobuf-deserialize-action`; for Avro, 
use `avro-serialize-action`.\n\nInput: parsed JSON (a Map or a Jackson 
`JsonNode`) whose fields match  [...]
     "group" : "Actions",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
@@ -2104,8 +2104,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "Replace Field Action",
-    "summary" : "Replace field with a different key in the message in 
transit.",
-    "description" : "Replace field with a different key in the message in 
transit.",
+    "summary" : "Renames fields of each message that is a JSON object, and can 
also keep only some fields or remove others.",
+    "description" : "Renames fields of each message that is a JSON object, and 
can also keep only some fields or remove others.\n\nUse it to match the field 
names another system expects, such as `name` to `fullName`, and to leave out 
the fields it should not get. To remove a single field, `drop-field-action` is 
simpler; to hide a value but keep the field, use `mask-field-action`.\n\nInput: 
a JSON object, as JSON text or as parsed JSON (a Map or a Jackson `JsonNode`). 
Only the fields at t [...]
     "group" : "Actions",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
@@ -2114,8 +2114,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "Resolve Schema Action",
-    "summary" : "Resolves schema from given mime type and payload. Sets the 
resolved schema, the schema type and its content class as properties for later 
reference.",
-    "description" : "Resolves schema from given mime type and payload. Sets 
the resolved schema, the schema type and its content class as properties for 
later reference.",
+    "summary" : "Attaches an Avro, Protobuf or JSON schema to each message, 
for the later steps that need one, and leaves the body unchanged.",
+    "description" : "Attaches an Avro, Protobuf or JSON schema to each 
message, for the later steps that need one, and leaves the body 
unchanged.\n\nUse it to give the schema once, before `data-type-action` with a 
format such as `avro-binary` or `protobuf-binary`, which takes its schema only 
from here. `avro-serialize-action`, `avro-deserialize-action`, 
`protobuf-serialize-action` and `protobuf-deserialize-action` use it too when 
their own `schema` is not set.\n\nInput: any body. The sch [...]
     "group" : "Actions",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
@@ -2214,8 +2214,8 @@
     "type" : "action",
     "supportLevel" : "Stable",
     "title" : "Set Body Action",
-    "summary" : "Sets a simple language parsed value as the new message body 
in transit.",
-    "description" : "Sets a simple language parsed value as the new message 
body in transit.",
+    "summary" : "Replaces the body of each message with a text you write, 
which can include values from the message, such as a header.",
+    "description" : "Replaces the body of each message with a text you write, 
which can include values from the message, such as a header.\n\nUse it to send 
a fixed text or a small JSON document, such as a status message, or to build a 
short text from headers and the old body. For longer texts, a template Kamelet 
such as `mustache-template-action` is easier to maintain.\n\nInput: any 
message. In the text, `$\\{body}` is the old body and `${header.name}` the 
value of a header.\n\nOutput:  [...]
     "group" : "Actions",
     "namespace" : "Transformation",
     "provider" : "Apache Software Foundation"
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/avro-deserialize-action.kamelet.yaml
 
b/library/camel-kamelets/src/main/resources/kamelets/avro-deserialize-action.kamelet.yaml
index f3e0157b7..a37968aab 100644
--- 
a/library/camel-kamelets/src/main/resources/kamelets/avro-deserialize-action.kamelet.yaml
+++ 
b/library/camel-kamelets/src/main/resources/kamelets/avro-deserialize-action.kamelet.yaml
@@ -31,17 +31,26 @@ metadata:
 spec:
   definition:
     title: "Avro Deserialize Action"
-    description: "Deserialize payload to Avro."
+    description: |-
+      Turns each message of Avro binary data back into a JSON object, using 
the Avro schema the data was written with.
+
+      Use it to read records that arrive in Avro, a compact binary format 
described by a schema, for example from a Kafka topic, and work on them as 
JSON. To turn JSON into Avro, use `avro-serialize-action`; for Protobuf, use 
`protobuf-deserialize-action`.
+
+      Input: Avro binary data, as bytes, without the schema in it, such as 
`avro-serialize-action` writes.
+
+      Output: the body is parsed JSON (a Jackson `JsonNode`) with one field 
for each field of the schema. The `Content-Type` header is removed. Put 
`json-serialize-action` after this action to get JSON text.
+
+      Good to know: Avro data does not say which schema it was written with, 
so the schema must be the one the writer used. When `schema` is not set, the 
schema found by an earlier `resolve-pojo-schema-action` is used.
     type: object
     properties:
       schema:
         title: Schema
-        description: The Avro schema to use during serialization (as 
single-line, using JSON format)
+        description: "The Avro schema the data was written with, as JSON text: 
a record with a name and a list of fields, each with a name and a type. When it 
is not set, the schema found by an earlier `resolve-pojo-schema-action` is 
used."
         type: string
         example: '{"type": "record", "namespace": "com.example", "name": 
"FullName", "fields": [{"name": "first", "type": "string"},{"name": "last", 
"type": "string"}]}'
       validate:
         title: Validate
-        description: Indicates if the content must be validated against the 
schema
+        description: Meant to turn the check of the content against the schema 
on or off. It has no effect.
         type: boolean
         default: true
   dependencies:
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/avro-serialize-action.kamelet.yaml
 
b/library/camel-kamelets/src/main/resources/kamelets/avro-serialize-action.kamelet.yaml
index 2df6a9f20..b19fc2a0f 100644
--- 
a/library/camel-kamelets/src/main/resources/kamelets/avro-serialize-action.kamelet.yaml
+++ 
b/library/camel-kamelets/src/main/resources/kamelets/avro-serialize-action.kamelet.yaml
@@ -31,19 +31,35 @@ metadata:
 spec:
   definition:
     title: "Avro Serialize Action"
-    description: "Serialize payload to Avro."
+    description: |-
+      Turns each message, a JSON object, into Avro binary data that follows 
the Avro schema you give.
+
+      Use it to send records in Avro, a compact binary format described by a 
schema, to a system that expects it, such as a Kafka topic whose readers decode 
Avro. To turn Avro back into JSON, use `avro-deserialize-action`; for Protobuf, 
use `protobuf-serialize-action`.
+
+      Input: parsed JSON (a Map or a Jackson `JsonNode`) whose fields match 
the schema. JSON text fails: put `json-deserialize-action` before this action 
to parse it.
+
+      Output: the body is the Avro binary data, as bytes, and the 
`Content-Type` header is set to `application/avro`.
+
+      Good to know: the schema is not written into the data, so whoever reads 
it needs the same schema. A message fails when it lacks a field of the schema, 
has a field the schema does not know, or has a value of the wrong type. When 
`schema` is not set, the schema found by an earlier 
`resolve-pojo-schema-action` is used.
     type: object
     properties:
       schema:
         title: Schema
-        description: The Avro schema to use during serialization (as 
single-line, using JSON format)
+        description: "The Avro schema of the records, as JSON text: a record 
with a name and a list of fields, each with a name and a type. When it is not 
set, the schema found by an earlier `resolve-pojo-schema-action` is used."
         type: string
         example: '{"type": "record", "namespace": "com.example", "name": 
"FullName", "fields": [{"name": "first", "type": "string"},{"name": "last", 
"type": "string"}]}'
       validate:
         title: Validate
-        description: Indicates if the content must be validated against the 
schema
+        description: "Meant to turn the check of the content against the 
schema on or off. It has no effect: a message that does not match the schema 
always fails."
         type: boolean
         default: true
+  dataTypes:
+    out:
+      headers:
+        Content-Type:
+          title: Content Type
+          description: Always `application/avro`.
+          type: string
   dependencies:
   - "camel:kamelet"
   - "camel:jackson-avro"
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/data-type-action.kamelet.yaml
 
b/library/camel-kamelets/src/main/resources/kamelets/data-type-action.kamelet.yaml
index 306aac065..af6b1794e 100644
--- 
a/library/camel-kamelets/src/main/resources/kamelets/data-type-action.kamelet.yaml
+++ 
b/library/camel-kamelets/src/main/resources/kamelets/data-type-action.kamelet.yaml
@@ -30,19 +30,37 @@ metadata:
 spec:
   definition:
     title: "Data Type Action"
-    description: Applies a given data type with respective data transformation.
+    description: |-
+      Converts the body of each message into the data type you name, such as 
plain text, bytes, JSON, Avro or Protobuf, and sets the `Content-Type` header 
to match.
+
+      Use it to give the next step the kind of body it needs, such as bytes 
for a sink that writes files, or to turn JSON into Avro binary data after 
`resolve-pojo-schema-action` has found the schema. A data type is a name for a 
kind of body together with the conversion into it; `camel catalog transformer` 
lists the names.
+
+      Input: `text-plain` and `application-octet-stream` take any text; 
`application-json` and `application-x-struct` take JSON text; `avro-binary` and 
`protobuf-binary` take a JSON object, as JSON text or a Jackson `JsonNode` but 
not a Map; `avro-x-struct` and `protobuf-x-struct` take Avro or Protobuf binary 
data.
+
+      Output: `text-plain` gives text (`Content-Type` `text/plain`); 
`application-octet-stream` bytes (`application/octet-stream`); 
`application-json` JSON text as bytes (`application/json`); the `x-struct` ones 
parsed JSON, a Jackson `JsonNode` (`application/x-struct`); `avro-binary` and 
`protobuf-binary` binary data (`avro/binary`, `protobuf/binary`). 
`application-cloudevents+json` wraps the body, under `data`, in a CloudEvents 
JSON envelope.
+
+      Good to know: a name that does not exist makes every message fail, and 
so do the Avro and Protobuf data types without a schema from an earlier 
`resolve-pojo-schema-action`. With `text-plain`, a Map becomes text such as 
`{id=1, name=Ann}`, not JSON.
     required:
       - format
     type: object
     properties:
       scheme:
         title: Component Scheme
-        description: The data type component scheme enables users to apply 
Camel component specific data type conversions.
+        description: The name of a system, as Camel names it, such as 
`aws2-s3`, to use the data type made for that system instead of the general 
one. With `aws2-s3` and the format `application-cloudevents`, the data type 
`aws2-s3:application-cloudevents` is used. Leave it empty for the general data 
types.
         type: string
+        example: aws2-s3
       format:
         title: Data Type Format
-        description: Defines the data type that is applied by this action. 
Apache Camel and the Kamelet catalog support different data types and performs 
automatic message conversion according to the given type.
+        description: The name of the data type to convert the body into, such 
as `text-plain`, `application-octet-stream`, `application-json`, 
`application-x-struct`, `avro-binary`, `avro-x-struct`, `protobuf-binary`, 
`protobuf-x-struct` or `application-cloudevents+json`. `camel catalog 
transformer` lists them all; for the names written `scheme:format`, such as 
`aws2-s3:application-cloudevents`, put the part before the colon in `scheme`.
         type: string
+        example: application-json
+  dataTypes:
+    out:
+      headers:
+        Content-Type:
+          title: Content Type
+          description: The kind of body the data type gives, such as 
`text/plain`, `application/json` or `avro/binary`.
+          type: string
   dependencies:
     - "camel:kamelet"
   template:
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/drop-field-action.kamelet.yaml
 
b/library/camel-kamelets/src/main/resources/kamelets/drop-field-action.kamelet.yaml
index 96aa679ec..33a322e85 100644
--- 
a/library/camel-kamelets/src/main/resources/kamelets/drop-field-action.kamelet.yaml
+++ 
b/library/camel-kamelets/src/main/resources/kamelets/drop-field-action.kamelet.yaml
@@ -30,15 +30,32 @@ metadata:
 spec:
   definition:
     title: "Drop Field Action"
-    description: Removes a custom field by given name from the message in 
transit.
+    description: |-
+      Removes one field, chosen by its name, from each message that is a JSON 
object.
+
+      Use it to take out a field that the next system does not accept or 
should not see, such as an internal ID or a password. To remove several fields, 
or to keep only some, use `replace-field-action`; to keep the field but hide 
its value, use `mask-field-action`.
+
+      Input: a JSON object, as JSON text or as parsed JSON (a Map or a Jackson 
`JsonNode`). Only the fields at the top level of the object are looked at. A 
JSON array is passed on unchanged; a body that is not JSON fails.
+
+      Output: the same object without the field. When the `Content-Type` 
header is `application/json`, the body is JSON text again; otherwise it is 
parsed JSON (a Jackson `JsonNode`), which `json-serialize-action` turns into 
JSON text.
+
+      Good to know: a message without the field is passed on unchanged. A 
field of the same name inside a nested object is not removed.
     required:
       - field
     properties:
       field:
         title: Field
-        description: The name of the field to be removed
+        description: The name of the top-level field to remove from the JSON 
object.
         type: string
+        example: password
     type: object
+  dataTypes:
+    in:
+      headers:
+        Content-Type:
+          title: Content Type
+          description: When it is `application/json`, the body is read as JSON 
text and written back as JSON text. Otherwise the body comes out as parsed JSON.
+          type: string
   dependencies:
   - "camel:jackson"
   - "camel:kamelet"
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/extract-field-action.kamelet.yaml
 
b/library/camel-kamelets/src/main/resources/kamelets/extract-field-action.kamelet.yaml
index 40b8f798e..ef246c637 100644
--- 
a/library/camel-kamelets/src/main/resources/kamelets/extract-field-action.kamelet.yaml
+++ 
b/library/camel-kamelets/src/main/resources/kamelets/extract-field-action.kamelet.yaml
@@ -30,35 +30,59 @@ metadata:
 spec:
   definition:
     title: "Extract Field Action"
-    description: Extract a field from the message body.
+    description: |-
+      Replaces the body of each message that is a JSON object with the value 
of one of its fields, or copies that value into a header.
+
+      Use it to keep only the part of a message you need, such as the 
`payload` of an event or the `email` of a customer, or, with `headerOutput`, to 
have that value in a header for a later step while the body stays as it is. To 
do the opposite, and wrap a body in a field, use `hoist-field-action`.
+
+      Input: a JSON object, as JSON text or as parsed JSON (a Map or a Jackson 
`JsonNode`). The field must be at the top level of the object. A JSON array, or 
a body that is not JSON, fails.
+
+      Output: the body is the value of the field. When the `Content-Type` 
header is `application/json`, it is JSON text, so a text value keeps its quotes 
(`"Ann"`) unless `trimField` is true; otherwise it is the value itself, such as 
the text `Ann`. When `headerOutput` is true, the value goes into the header 
`CamelKameletsExtractFieldName`, or the header named by `headerOutputName`, and 
the body is left as it was.
+
+      Good to know: when the object does not have the field, the body or the 
header is empty (the JSON text `null` when the `Content-Type` header is 
`application/json`); the message does not fail.
     required:
       - field
     properties:
       field:
         title: Field
-        description: The name of the field to extract
+        description: The name of the top-level field whose value to take.
         type: string
+        example: email
       headerOutput:
         title: Header Output
-        description: If enable the action will store the extracted field in an 
header named CamelKameletsExtractFieldName
+        description: If true, the value is put in a header, 
`CamelKameletsExtractFieldName` unless `headerOutputName` is set, and the body 
is left as it was. If false, the value replaces the body.
         type: boolean
         default: false
       headerOutputName:
         title: Header Output Name
-        description: A custom name for the header containing the extracted 
field
+        description: The name of the header to put the value in. Only used 
when `headerOutput` is true. The default, `none`, means the header 
`CamelKameletsExtractFieldName`.
         default: "none"
         type: string
+        example: customerEmail
       strictHeaderCheck:
         title: Strict Header Check
-        description: If enabled the action will check if the header output 
name (custom or default) has been used already in the exchange. If so, the 
extracted field is stored in the message body, if not, the extracted field is 
stored in the selected header (custom or default).
+        description: Only used when `headerOutput` is true. If true, and the 
message already has the header, the header keeps its old value and the value of 
the field replaces the body instead.
         type: boolean
         default: false
       trimField:
         title: Trim Field
-        description: If enabled we return the Raw extracted field
+        description: If true, the body is the plain value, such as `Ann`, 
instead of JSON text such as `"Ann"`. It changes something only when the 
`Content-Type` header is `application/json`, and that header is then left as it 
is.
         type: boolean
         default: false
     type: object
+  dataTypes:
+    in:
+      headers:
+        Content-Type:
+          title: Content Type
+          description: When it is `application/json`, the body is read as JSON 
text and the value is written as JSON text, unless `trimField` is true.
+          type: string
+    out:
+      headers:
+        CamelKameletsExtractFieldName:
+          title: Extracted Field
+          description: The value of the field, when `headerOutput` is true and 
`headerOutputName` is not set.
+          type: string
   dependencies:
   - "camel:kamelet"
   - "camel:jackson"
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/hoist-field-action.kamelet.yaml
 
b/library/camel-kamelets/src/main/resources/kamelets/hoist-field-action.kamelet.yaml
index 184c5dedc..669416cce 100644
--- 
a/library/camel-kamelets/src/main/resources/kamelets/hoist-field-action.kamelet.yaml
+++ 
b/library/camel-kamelets/src/main/resources/kamelets/hoist-field-action.kamelet.yaml
@@ -30,15 +30,36 @@ metadata:
 spec:
   definition:
     title: "Hoist Field Action"
-    description: "Wrap data in a single field."
+    description: |-
+      Wraps the body of each message in a new JSON object, as the value of the 
one field you name.
+
+      Use it to nest the whole message under one name, for example to turn 
`{"id":1}` into `{"order":{"id":1}}` for a system that expects that shape. To 
do the opposite, and take the value out of a field, use `extract-field-action`.
+
+      Input: any body. JSON is nested as a JSON object or array when it is 
parsed JSON (a Map or a Jackson `JsonNode`), or JSON text with the 
`Content-Type` header `application/json`. Any other text, including JSON text 
with another `Content-Type`, becomes a text value: `hello` gives 
`{"order":"hello"}`.
+
+      Output: the body is the new JSON object, as JSON text, and the 
`Content-Type` header is set to `application/json`.
     required:
       - field
     properties:
       field:
         title: Field
-        description: The name of the field that will contain the event.
+        description: The name of the field that holds the body in the new JSON 
object.
         type: string
+        example: order
     type: object
+  dataTypes:
+    in:
+      headers:
+        Content-Type:
+          title: Content Type
+          description: When it is `application/json`, JSON text in the body is 
nested as JSON. Otherwise text is nested as a text value.
+          type: string
+    out:
+      headers:
+        Content-Type:
+          title: Content Type
+          description: Always `application/json`.
+          type: string
   dependencies:
   - "camel:jackson"
   - "camel:kamelet"
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/insert-field-action.kamelet.yaml
 
b/library/camel-kamelets/src/main/resources/kamelets/insert-field-action.kamelet.yaml
index 5d82f6246..1dac2646c 100644
--- 
a/library/camel-kamelets/src/main/resources/kamelets/insert-field-action.kamelet.yaml
+++ 
b/library/camel-kamelets/src/main/resources/kamelets/insert-field-action.kamelet.yaml
@@ -30,20 +30,38 @@ metadata:
 spec:
   definition:
     title: "Insert Field Action"
-    description: Adds a custom field with a simple language parsed value to 
the message in transit.
+    description: |-
+      Adds a field with a value you choose to each message that is a JSON 
object, or replaces the value when the field is already there.
+
+      Use it to tag records with where they come from or which environment 
they passed through, or to add a value from a header or the current date. To 
add a header instead of a field, use `insert-header-action`.
+
+      Input: a JSON object, as JSON text or as parsed JSON (a Map or a Jackson 
`JsonNode`). When the body is a JSON array, the value is added at the end of 
the array and `field` is not used. A body that is not JSON fails.
+
+      Output: the object with the field. When the `Content-Type` header is 
`application/json`, the body is JSON text again; otherwise it is parsed JSON (a 
Jackson `JsonNode`), which `json-serialize-action` turns into JSON text.
+
+      Good to know: the value is always added as a JSON text value, in quotes, 
even when it looks like a number. The field is added at the top level of the 
object.
     required:
       - field
       - value
     properties:
       field:
         title: Field
-        description: The name of the field to be added.
+        description: The name of the top-level field to add. When the object 
already has a field of this name, its value is replaced.
         type: string
+        example: source
       value:
         title: Value
-        description: The value of the field.
+        description: "The value of the new field, as text. It can include 
values from the message: `${header.name}` is the value of a header, 
`${date:now:yyyy-MM-dd}` the current date."
         type: string
+        example: "shop-${header.region}"
     type: object
+  dataTypes:
+    in:
+      headers:
+        Content-Type:
+          title: Content Type
+          description: When it is `application/json`, the body is read as JSON 
text and written back as JSON text. Otherwise the body comes out as parsed JSON.
+          type: string
   dependencies:
   - "camel:jackson"
   - "camel:kamelet"
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/mask-field-action.kamelet.yaml
 
b/library/camel-kamelets/src/main/resources/kamelets/mask-field-action.kamelet.yaml
index ef8666dce..03685ae2f 100644
--- 
a/library/camel-kamelets/src/main/resources/kamelets/mask-field-action.kamelet.yaml
+++ 
b/library/camel-kamelets/src/main/resources/kamelets/mask-field-action.kamelet.yaml
@@ -30,20 +30,38 @@ metadata:
 spec:
   definition:
     title: "Mask Fields Action"
-    description: "Mask fields with a constant value in the message in transit."
+    description: |-
+      Replaces the values of the fields you name in each message that is a 
JSON object with a fixed value, such as `XXXX`.
+
+      Use it to hide card numbers, passwords or personal data before the 
messages are logged or sent to another system. To remove a field entirely, use 
`drop-field-action`, or `replace-field-action` for several fields.
+
+      Input: a JSON object, as JSON text or as parsed JSON (a Map or a Jackson 
`JsonNode`). Only the fields at the top level of the object are masked; nested 
objects are left as they are. A JSON array, or a body that is not JSON, fails.
+
+      Output: the object with the masked values; the order of its fields can 
change. When the `Content-Type` header is `application/json`, the body is JSON 
text again; otherwise it is parsed JSON (a Jackson `JsonNode`), which 
`json-serialize-action` turns into JSON text.
+
+      Good to know: the replacement must suit the value it replaces. A text 
value takes any replacement, but a number takes only a number, such as `0`, and 
a true or false value, an object or a list cannot be masked: such a message 
fails. A named field that the object does not have is ignored.
     required:
       - fields
       - replacement
     properties:
       fields:
         title: Fields
-        description: Comma separated list of fields to mask
+        description: The names of the top-level fields to mask, separated by 
commas.
         type: string
+        example: "card,password"
       replacement:
         title: Replacement
-        description: Replacement for the fields to be masked
+        description: The value that replaces the value of each masked field. 
Any text works for a text value; a number value needs a number, such as `0`.
         type: string
+        example: "****"
     type: object
+  dataTypes:
+    in:
+      headers:
+        Content-Type:
+          title: Content Type
+          description: When it is `application/json`, the body is read as JSON 
text and written back as JSON text. Otherwise the body comes out as parsed JSON.
+          type: string
   dependencies:
   - "camel:jackson"
   - "camel:kamelet"
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/protobuf-deserialize-action.kamelet.yaml
 
b/library/camel-kamelets/src/main/resources/kamelets/protobuf-deserialize-action.kamelet.yaml
index dca9bdf2d..33bf21f85 100644
--- 
a/library/camel-kamelets/src/main/resources/kamelets/protobuf-deserialize-action.kamelet.yaml
+++ 
b/library/camel-kamelets/src/main/resources/kamelets/protobuf-deserialize-action.kamelet.yaml
@@ -30,12 +30,21 @@ metadata:
 spec:
   definition:
     title: "Protobuf Deserialize Action"
-    description: "Deserialize payload to Protobuf."
+    description: |-
+      Turns each message of Protobuf binary data back into a JSON object, 
using the Protobuf schema the data was written with.
+
+      Use it to read records that arrive in Protocol Buffers (Protobuf), a 
compact binary format described by a schema, and work on them as JSON. To turn 
JSON into Protobuf, use `protobuf-serialize-action`; for Avro, use 
`avro-deserialize-action`.
+
+      Input: Protobuf binary data, as bytes, such as 
`protobuf-serialize-action` writes.
+
+      Output: the body is parsed JSON (a Jackson `JsonNode`) with the fields 
found in the data. The `Content-Type` header is removed. Put 
`json-serialize-action` after this action to get JSON text.
+
+      Good to know: a body that is not Protobuf data, such as JSON text, 
fails. When `schema` is not set, the schema found by an earlier 
`resolve-pojo-schema-action` is used.
     type: object
     properties:
       schema:
         title: Schema
-        description: The Protobuf schema to use during serialization (as 
single-line)
+        description: "The Protobuf schema the data was written with, in the 
`.proto` language: a `message` with its fields, each with a type, a name and a 
number. When it is not set, the schema found by an earlier 
`resolve-pojo-schema-action` is used."
         type: string
         example: 'message Person { required string first = 1; required string 
last = 2; }'
   dependencies:
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/protobuf-serialize-action.kamelet.yaml
 
b/library/camel-kamelets/src/main/resources/kamelets/protobuf-serialize-action.kamelet.yaml
index 3e72f106a..1f88100f3 100644
--- 
a/library/camel-kamelets/src/main/resources/kamelets/protobuf-serialize-action.kamelet.yaml
+++ 
b/library/camel-kamelets/src/main/resources/kamelets/protobuf-serialize-action.kamelet.yaml
@@ -30,14 +30,30 @@ metadata:
 spec:
   definition:
     title: "Protobuf Serialize Action"
-    description: "Serialize payload to Protobuf."
+    description: |-
+      Turns each message, a JSON object, into Protobuf binary data that 
follows the Protobuf schema you give.
+
+      Use it to send records in Protocol Buffers (Protobuf), a compact binary 
format described by a schema, to a system that expects it, such as a Kafka 
topic whose readers decode Protobuf. To turn Protobuf back into JSON, use 
`protobuf-deserialize-action`; for Avro, use `avro-serialize-action`.
+
+      Input: parsed JSON (a Map or a Jackson `JsonNode`) whose fields match 
the schema. Put `json-deserialize-action` before this action when the body is 
JSON text.
+
+      Output: the body is the Protobuf binary data, as bytes, and the 
`Content-Type` header is set to `application/protobuf`.
+
+      Good to know: JSON text is not turned into Protobuf: it is passed on as 
it is, yet the `Content-Type` header is set to `application/protobuf`. A 
message fails when it has a field the schema does not know or a value of the 
wrong type; a field of the schema that the message lacks is left out, even when 
it is marked `required`. When `schema` is not set, the schema found by an 
earlier `resolve-pojo-schema-action` is used.
     type: object
     properties:
       schema:
         title: Schema
-        description: The Protobuf schema to use during serialization (as 
single-line)
+        description: "The Protobuf schema of the records, in the `.proto` 
language: a `message` with its fields, each with a type, a name and a number. 
When it is not set, the schema found by an earlier `resolve-pojo-schema-action` 
is used."
         type: string
         example: 'message Person { required string first = 1; required string 
last = 2; }'
+  dataTypes:
+    out:
+      headers:
+        Content-Type:
+          title: Content Type
+          description: Always `application/protobuf`.
+          type: string
   dependencies:
   - "camel:kamelet"
   - "camel:jackson-protobuf"
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/replace-field-action.kamelet.yaml
 
b/library/camel-kamelets/src/main/resources/kamelets/replace-field-action.kamelet.yaml
index a4f4b866a..44f39f241 100644
--- 
a/library/camel-kamelets/src/main/resources/kamelets/replace-field-action.kamelet.yaml
+++ 
b/library/camel-kamelets/src/main/resources/kamelets/replace-field-action.kamelet.yaml
@@ -30,27 +30,44 @@ metadata:
 spec:
   definition:
     title: "Replace Field Action"
-    description: Replace field with a different key in the message in transit.
+    description: |-
+      Renames fields of each message that is a JSON object, and can also keep 
only some fields or remove others.
+
+      Use it to match the field names another system expects, such as `name` 
to `fullName`, and to leave out the fields it should not get. To remove a 
single field, `drop-field-action` is simpler; to hide a value but keep the 
field, use `mask-field-action`.
+
+      Input: a JSON object, as JSON text or as parsed JSON (a Map or a Jackson 
`JsonNode`). Only the fields at the top level of the object are renamed, kept 
or removed; nested objects are left as they are. A JSON array, or a body that 
is not JSON, fails.
+
+      Output: the object with the renamed fields, without the removed ones; 
the order of its fields can change. When the `Content-Type` header is 
`application/json`, the body is JSON text again; otherwise it is parsed JSON (a 
Jackson `JsonNode`), which `json-serialize-action` turns into JSON text.
+
+      Good to know: `renames` is required, even when you only want to keep or 
remove fields. A rename of a field the object does not have is ignored. When 
`enabled` and `disabled` together would remove every field, the object is 
passed on unchanged.
     required:
       - renames
     properties:
       enabled:
         title: Enabled
-        description: Comma separated list of top level fields to be enabled
+        description: The names of the top-level fields to keep, separated by 
commas; all the other fields are removed. The default, `all`, keeps every field.
         type: string
         default: "all"
+        example: "id,name"
       disabled:
         title: Disabled
-        description: Comma separated list of top level fields to be disabled
+        description: The names of the top-level fields to remove, separated by 
commas. The default, `none`, removes nothing.
         type: string
         default: "none"
+        example: "card,password"
       renames:
         title: Renames
-        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.
+        description: The fields to rename, as `old:new` pairs separated by 
commas. Only top-level fields are renamed; naming a field nested inside an 
object has no effect. A pair without `:` makes every message fail.
         type: string
-        example: "foo:bar,c1:c2"
+        example: "name:fullName,zip:postalCode"
     type: object
+  dataTypes:
+    in:
+      headers:
+        Content-Type:
+          title: Content Type
+          description: When it is `application/json`, the body is read as JSON 
text and written back as JSON text. Otherwise the body comes out as parsed JSON.
+          type: string
   types:
     in:
       mediaType: application/json
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/resolve-pojo-schema-action.kamelet.yaml
 
b/library/camel-kamelets/src/main/resources/kamelets/resolve-pojo-schema-action.kamelet.yaml
index 5e25eaf9f..6f64d949b 100644
--- 
a/library/camel-kamelets/src/main/resources/kamelets/resolve-pojo-schema-action.kamelet.yaml
+++ 
b/library/camel-kamelets/src/main/resources/kamelets/resolve-pojo-schema-action.kamelet.yaml
@@ -31,29 +31,39 @@ metadata:
 spec:
   definition:
     title: "Resolve Schema Action"
-    description: "Resolves schema from given mime type and payload. Sets the 
resolved schema, the schema type and its content class as properties for later 
reference."
+    description: |-
+      Attaches an Avro, Protobuf or JSON schema to each message, for the later 
steps that need one, and leaves the body unchanged.
+
+      Use it to give the schema once, before `data-type-action` with a format 
such as `avro-binary` or `protobuf-binary`, which takes its schema only from 
here. `avro-serialize-action`, `avro-deserialize-action`, 
`protobuf-serialize-action` and `protobuf-deserialize-action` use it too when 
their own `schema` is not set.
+
+      Input: any body. The schema comes from `schema`, or else from the Java 
class named by `contentClass`.
+
+      Output: the body and the headers are unchanged. The schema is kept with 
the message in the properties `X-Content-Schema` and `X-Content-Schema-Type` 
(`avsc`, `proto` or `json`), which are not headers and are not sent to other 
systems.
+
+      Good to know: with the default `mimeType`, `application/json`, and no 
`schema` or `contentClass`, it does nothing. A `mimeType` it does not know 
makes every message fail with "Unsupported type".
     type: object
     properties:
       mimeType:
-        title: Mime Type
-        description: The mime type to determine the schema resolver 
implementation that should perform the operation.
+        title: MIME Type
+        description: "Which kind of schema `schema` holds and later steps 
need: `avro/binary`, `application/avro` or `avro/x-struct` for Avro; 
`protobuf/binary`, `application/protobuf` or `protobuf/x-struct` for Protobuf; 
`application/json` or `application/x-struct` for JSON Schema. With 
`application/x-java-object`, the kind is taken from `targetMimeType`."
         type: string
         default: "application/json"
-        example: "application/json"
+        example: "avro/binary"
       schema:
         title: Schema
-        description: Optional schema content (as single-line, using JSON 
format).
+        description: "The schema itself: for Avro, JSON text such as the 
example; for Protobuf, a `message` in the `.proto` language; for JSON, a JSON 
Schema as JSON text. When it is not set, the schema is made from 
`contentClass`."
         type: string
+        example: '{"type": "record", "namespace": "com.example", "name": 
"FullName", "fields": [{"name": "first", "type": "string"},{"name": "last", 
"type": "string"}]}'
       contentClass:
         title: Content Class
-        description: Type information of the content object. Fully qualified 
class name.
+        description: The full name of a Java class in the application whose 
fields define the schema. Only used when `schema` is not set.
         type: string
-        example: "org.apache.camel.content.Foo"
+        example: "com.example.Order"
       targetMimeType:
-        title: Target Mime Type
-        description: Additional mime type information used to determine the 
schema resolver. Usually only used in combination with mime type 
"application/x-java-object"
+        title: Target MIME Type
+        description: The kind of schema to find, as in `mimeType`, such as 
`avro/binary`. Only used when `mimeType` is `application/x-java-object`.
         type: string
-        example: "application/json"
+        example: "avro/binary"
   dependencies:
     - "camel:kamelet"
     - "camel:jackson-avro"
diff --git 
a/library/camel-kamelets/src/main/resources/kamelets/set-body-action.kamelet.yaml
 
b/library/camel-kamelets/src/main/resources/kamelets/set-body-action.kamelet.yaml
index 7bc125be2..cf9c3493a 100644
--- 
a/library/camel-kamelets/src/main/resources/kamelets/set-body-action.kamelet.yaml
+++ 
b/library/camel-kamelets/src/main/resources/kamelets/set-body-action.kamelet.yaml
@@ -31,14 +31,24 @@ metadata:
 spec:
   definition:
     title: "Set Body Action"
-    description: Sets a simple language parsed value as the new message body 
in transit.
+    description: |-
+      Replaces the body of each message with a text you write, which can 
include values from the message, such as a header.
+
+      Use it to send a fixed text or a small JSON document, such as a status 
message, or to build a short text from headers and the old body. For longer 
texts, a template Kamelet such as `mustache-template-action` is easier to 
maintain.
+
+      Input: any message. In the text, `$\{body}` is the old body and 
`${header.name}` the value of a header.
+
+      Output: the body is the text, with the values filled in. The headers are 
kept as they were, `Content-Type` too, so set it to match the new body when 
needed, for example with `insert-header-action`.
+
+      Good to know: up to Camel 4.23, two closing braces in a row are read as 
the end of a placeholder and make the Kamelet fail to start, so write nested 
JSON with a space between them, as `} }`.
     required:
       - value
     properties:
       value:
         title: Value
-        description: The value to set as new body
+        description: "The new body, as text. `$\\{body}` is replaced by the 
old body, `${header.name}` by the value of the header `name`, and 
`${date:now:yyyy-MM-dd}` by the current date."
         type: string
+        example: "Order ${header.orderId} received"
     type: object
   dependencies:
   - "camel:kamelet"

Reply via email to