This is an automated email from the ASF dual-hosted git repository.
oscerd 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 d47290995 chore: document declaring Kamelet headers without a
transformation (#328) (#3083)
d47290995 is described below
commit d47290995f8885925e7e5a37c1e2cec60ea14264
Author: Andrea Cosentino <[email protected]>
AuthorDate: Sun Oct 4 15:23:37 2026 +0200
chore: document declaring Kamelet headers without a transformation (#328)
(#3083)
The "Kamelet data types" section explains dataTypes entirely in terms of
offering a choice of formats, each backed by a transformer. Nothing said
a Kamelet that transforms nothing can still declare the headers it emits
or reads, and #328 and #929 were both argued on the assumption that it
cannot -- that the declaration hangs off dataTypes, so a non-transforming
Kamelet has nowhere natural to put it.
That assumption is wrong. A headers block is valid on its own, with no
types and no default. Verified three ways:
* Runtime: added dataTypes.in.headers to log-sink, which has no dataTypes
block at all, and ran it on Camel 4.22.0. The context started and
processed a message normally.
* Catalog: KameletsCatalog.getDeclaredHeaders iterates the dataTypes
values and reads getHeaders() without requiring types, so the
declaration is what getKameletSupportedHeaders answers with.
* Build: added the same shape to aws-kinesis-source and ran a full root
build. CatalogValidator accepts it and the resource copy propagates it.
So document it, with why it is worth the few lines: the component
fallback answers a different question -- everything the component can
emit -- and because it follows the component, the catalog's header test
tracks upstream Camel for every Kamelet that declares nothing.
Also states the precedence #3075 settled: where a side declares both a
top-level headers block and headers inside its types, the top-level
block wins, because those are present whichever data type is in use.
Documentation only. No Kamelet, schema or code change, and this covers
only the convention part of #328 -- validator enforcement and payload
examples are still open there.
Signed-off-by: Andrea Cosentino <[email protected]>
Co-authored-by: Claude Opus 5 <[email protected]>
---
docs/modules/ROOT/pages/development.adoc | 42 ++++++++++++++++++++++++++++++++
1 file changed, 42 insertions(+)
diff --git a/docs/modules/ROOT/pages/development.adoc
b/docs/modules/ROOT/pages/development.adoc
index f80c18976..48074a7f2 100644
--- a/docs/modules/ROOT/pages/development.adoc
+++ b/docs/modules/ROOT/pages/development.adoc
@@ -466,6 +466,48 @@ The Pipe in the sample above uses a combination of Kamelet
output data type, Jso
All referenced data types are backed by a specific transformer implementation
either provided by the Kamelet itself or by pure Apache Camel functionality.
+=== Declaring headers without a transformation
+
+The `dataTypes` block above exists to offer a choice of formats, each one
backed by a transformer.
+A Kamelet that transforms nothing still has a contract worth declaring: the
headers it puts on
+every message, or the ones it reads. The `headers` block may be declared on
its own for that,
+with no `types` and no `default`.
+
+.my-plain-source.kamelet.yaml
+[source,yaml]
+----
+spec:
+ definition:
+# ...
+ dataTypes:
+ out: # <1>
+ headers:
+ MyHeaderName:
+ type: string
+ description: What this source puts on every message
+----
+<1> A `headers` block with no `types` and no `default`. Nothing is
transformed; this only
+describes what the Kamelet emits.
+
+A source declares the headers it emits under `out`; a sink or action declares
the ones it
+consumes under `in`.
+
+Declaring them is worth the few lines for two reasons:
+
+* `KameletsCatalog.getKameletSupportedHeaders` answers from the declaration
wherever there is
+ one, and falls back to the headers of the underlying Camel component only
where there is not.
+ The component list answers a different question -- everything that component
can emit -- so it
+ both over-reports headers a template never surfaces and misses the ones the
template sets
+ itself.
+* Because that fallback follows the component, the catalog's own header test
has to track
+ upstream Apache Camel: a header added to a component upstream changes what
the catalog reports
+ for every Kamelet that does not declare its own. Declaring them takes a
Kamelet out of that
+ dependency.
+
+Where a side declares both a top-level `headers` block and headers inside its
`types`, the
+top-level block is the answer. Those are the headers present whichever data
type is in use, while
+a type's headers appear only when that type is selected.
+
== Creating a complex Kamelet
We're now going to create a Kamelet with a high degree of complexity, to show
how the Kamelet model can be used also to go over the
