oscerd commented on issue #328:
URL: https://github.com/apache/camel-kamelets/issues/328#issuecomment-5926990176
Concrete proposal, as offered. Two things changed my view of this issue
since my last comment, and both make it cheaper than it looked.
## 1. The assumed blocker does not exist
My earlier comment said the declaration "hangs off `dataTypes`, so a Kamelet
that does no data type transformation has no natural place to put it". I tested
that rather than assuming it. It is **not** true at the runtime level.
I added this to `log-sink` — a Kamelet with no `dataTypes` block at all —
with no `types` and no `default`:
```yaml
dataTypes:
in:
headers:
X-Probe-Header:
title: Probe
description: A header declared with no types block at all
type: string
```
and ran it on Camel 4.22.0:
```
Apache Camel 4.22.0 (probe) started in 275ms
log-sink : Exchange[ExchangePattern: InOnly, BodyType: String, Body: hello]
```
It starts and processes normally. `KameletsCatalog.getDeclaredHeaders` reads
it too, because it iterates `dataTypes` values and reads `.getHeaders()`
without requiring `types`. So **a non-transforming Kamelet can already declare
headers and media types today** — no schema change, no decoupling work. What is
missing is a convention saying it should, and something that checks.
That answers design question 1 as "already possible", which is a materially
different proposition from "needs the declaration decoupled from `dataTypes`".
## 2. The cost of not doing it is measurable, and it is paid in CI
`KameletsCatalogTest.testSupportedHeaders` makes **116 assertions across 115
Kamelets**. Of those:
- **9** are insulated — the Kamelet declares its own headers, so the
assertion is about this repository;
- **105** are component-derived, of which **87 have a non-zero hard-coded
count** — each a number that breaks the build whenever Camel adds or removes a
header upstream.
That is not hypothetical. Commits whose sole purpose was re-syncing those
counts:
| commit | cause |
|---|---|
| #3071 (30 Sep 2026) | CAMEL-24935 added `CamelPulsarProducerMessageId` →
`pulsar-sink` 5 → 6 |
| #3051 | Camel shipped no metadata for a component at all |
| `69acf1c9c` | "Change header counts to match 4.21.0-SNAPSHOT component
changes" |
| #2775 | `google-mail-source` 8 → 9 |
| `ce2d6b347` | CAMEL-23032 added `CamelNatsDeliveryCounter` |
plus most "Upgrade to Camel 4.x" commits touching the same file. Every one
of those is a maintenance tax that a declared header set would not have
incurred — and #3061 plus #3075 are what make declaring actually pay off, since
the catalog now returns the declaration rather than the component list.
So the argument for this issue is no longer only "it would be nice if the
docs said what a source emits". It is also that the catalog's own test suite is
87 assertions deep in a dependency on upstream metadata it does not control.
## Proposal
**A. Convention, not schema.** Document in `development.adoc` that a source
SHOULD declare `spec.dataTypes.out.headers` and its output `mediaType`, and a
sink/action its input, whether or not it transforms anything. No CRD change, no
new annotation. This is the piece that was thought to be blocked and is not.
**B. Validator rule, warning first.** Add a `CatalogValidator` check that
reports a Kamelet with no declaration for its own side. Start as a warning —
243 of 262 Kamelets would trip it on day one, so failing the build immediately
is not viable. It makes the gap visible and stops it growing, and the count
becomes a number that can be driven down.
**C. Backfill opportunistically.** Convert component-derived test assertions
to declared ones as Kamelets are touched for other reasons, rather than as one
243-file change. Each conversion removes one upstream-coupled assertion.
Prioritise the 87 non-zero ones, since those are the ones that actually break.
**D. Point 3 of this issue — payload examples — stays open.** There is
genuinely no mechanism: no `example` on `dataTypes` headers or types, and
nothing in the CRD for a sample payload. It needs a schema addition, and I
would keep it separate from A–C rather than let it block them.
## What I am not proposing
A `Deprecated`-style new support level, a new top-level `spec` section, or a
big-bang backfill. A and B are small and reversible; C is incremental; D is the
only part that needs a schema conversation.
Happy to implement A and B if that shape is agreeable — B is the one worth a
second opinion, since a warning that fires on 93% of the catalog is either
useful pressure or just noise, depending on taste.
---
_Claude Code on behalf of Andrea Cosentino_
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
