Skip to content

headers.adoc

Latest commit

 

History

History
222 lines (161 loc) · 6.73 KB

headers.adoc

File metadata and controls

222 lines (161 loc) · 6.73 KB
Raw
title Exchange header naming conventions
authors
@oscerd
@gnodet
reviewers
approvers
creation-date 2026-05-22
last-updated 2026-05-22
status implementable
see-also
replaces
superseded-by

Summary

This document defines the naming conventions for Apache Camel Exchange headers. All component headers must follow these rules so that header names are predictable, self-documenting, and compatible with the framework’s HeaderFilterStrategy security mechanism.

Motivation

Camel has 300+ components, many contributed independently over 15+ years. Without a written standard, header string values drifted into at least four different styles: dns.name, QUERY, operationName, kafka.PARTITION_KEY. This inconsistency causes:

  • Confusion for users who must memorize per-component formats.

  • Security gaps: DefaultHeaderFilterStrategy strips Camel* headers case-insensitively. Headers that don’t use the Camel prefix bypass this filter, which matters when untrusted input flows through the Exchange (see security.adoc).

  • Tooling friction: code generators, catalog introspection, and IDE completion work best when header names follow a single predictable pattern.

Convention

Header string values

Every component-owned Exchange header string value MUST follow:

"Camel" + ComponentName + Feature

All segments are PascalCase, concatenated without separators.

Component Java constant String value

camel-kafka

KafkaConstants.TOPIC

CamelKafkaTopic

camel-file

FileConstants.FILE_NAME

CamelFileName

camel-jira

JiraConstants.ISSUE_KEY

CamelJiraIssueKey

camel-pdf

PdfHeaderConstants.PDF_DOCUMENT_HEADER_NAME

CamelPdfDocument

ComponentName is the PascalCase form of the Camel component scheme (e.g., kafka → Kafka, elasticsearch → Elasticsearch, aws2-s3 → Aws2S3).

Core framework headers

Headers defined in org.apache.camel.Exchange use the Camel prefix directly (no component name), because they are framework-wide:

CamelFileName, CamelHttpResponseCode, CamelBatchSize, ...

Java constant names

Java constant field names use UPPER_SNAKE_CASE:

public static final String ISSUE_KEY = "CamelJiraIssueKey";

The constant name describes the concept; the string value encodes the component namespace.

Constants class

Each component declares its header constants in a dedicated class:

<ComponentName>Constants.java

located in the component’s main package (org.apache.camel.component.<name>).

Each constant MUST carry an @Metadata annotation:

@Metadata(description = "The issue key", javaType = "String")
public static final String ISSUE_KEY = "CamelJiraIssueKey";

The @Metadata annotation drives automatic documentation generation (component doc pages, catalog JSON, Endpoint DSL).

Header prefix constants

Some components use prefix-based headers (e.g., CamelSolrField.title, CamelSolrParam.rows). The prefix constant follows the same convention:

public static final String HEADER_FIELD_PREFIX = "CamelSolrField.";

Protocol and standard headers

Headers that are part of an external wire protocol or standard (HTTP headers, JMS properties, Swift API headers, etc.) are exempt from the Camel prefix rule. They use the standard’s own name because the framework passes them through to the underlying transport.

Examples:

  • Swift: X-Container-Meta-, X-Versions-Location

  • HTTP: Content-Type, Accept

  • JMS: standard JMS property names

When a component has both Camel-convention headers and protocol pass-through headers, document the distinction clearly (see camel-openstack Swift constants for an example).

Exchange properties

Exchange properties (set via Exchange.setProperty()) are internal to the route and are NOT visible to HeaderFilterStrategy. They do not require the Camel prefix, though many core properties use it by convention.

Security interaction

The Camel* prefix is not just cosmetic. DefaultHeaderFilterStrategy strips headers matching Camel* and org.apache.camel.* case-insensitively from inbound messages. This prevents untrusted external senders from injecting Camel-internal routing directives.

When a component header does not use the Camel prefix, it bypasses this security filter entirely. This is why aligning all component headers to the Camel* namespace is both a consistency improvement and a security hardening measure.

See the security.adoc design document and the ROOT:security-model.adoc for the full threat model.

Renaming existing headers

When renaming a non-conforming header to follow this convention:

What to change

  1. Update the string value in the constants class.

  2. Regenerate all downstream artifacts:

    • mvn install -pl <module> -DskipTests

    • mvn install -pl catalog/camel-catalog -DskipTests

    • mvn generate-sources -pl dsl/camel-endpointdsl -DskipTests

    • mvn generate-sources -pl dsl/camel-componentdsl -DskipTests

  3. Update documentation (.adoc files, Javadoc) to reference the new names.

  4. Update tests to use the Java constants (not literal strings).

Upgrade guide

Every header rename is a breaking change and MUST be documented in the upgrade guide (docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_XX.adoc):

  • List every old value → new value.

  • Note which Endpoint DSL method names changed.

  • State that code using the Java constants is unaffected.

  • Warn that code using literal string header names must be updated.

Backward compatibility

The project’s current policy (as of 4.21) is a hard break with no deprecated aliases. The Java constant names stay the same, so code using constants compiles and works without changes. But code using literal header strings (XML/YAML routes, Simple expressions, tests with hardcoded strings) will silently stop matching.

This trade-off favors a clean, consistent header namespace over a gradual migration. The upgrade guide is the primary migration aid.

Backport policy

When a header rename is backported to a maintenance branch (e.g., camel-4.18.x, camel-4.14.x):

  • Add an upgrade guide entry on the maintenance branch.

  • Also add the corresponding entry on main to keep the version-specific upgrade guides in sync (see backport upgrade-guide policy in the project contribution guidelines).

Scope

This convention applies to:

  • All new components (mandatory).

  • Existing components when headers are modified for any reason (opportunistic alignment).

  • Dedicated alignment PRs (the ongoing CAMEL-2357x/CAMEL-2359x effort).

Headers in core (Exchange.java) already follow the convention and are not being renamed.