diff --git a/CHANGELOG.md b/CHANGELOG.md index 38176c8bb62..7d2589048d0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -91,6 +91,8 @@ release. - Align definition of Baggage with W3C Specification. ([#3800](https://github.com/open-telemetry/opentelemetry-specification/pull/3800)) +- Specify allowed characters for Baggage keys and values. + ([#3801](https://github.com/open-telemetry/opentelemetry-specification/pull/3801)) ### Traces diff --git a/specification/baggage/api.md b/specification/baggage/api.md index be39ba59578..928ba2609c8 100644 --- a/specification/baggage/api.md +++ b/specification/baggage/api.md @@ -35,6 +35,32 @@ with _exactly one value_. This is more restrictive than the [W3C Baggage Specification, § 3.2.1.1](https://www.w3.org/TR/baggage/#baggage-string) which allows duplicate entries for a given name. +Baggage **names** are any valid UTF-8 strings. Language API SHOULD NOT +restrict which strings are used as baggage **names**. However, the +specific `Propagator`s that are used to transmit baggage entries across +component boundaries may impose their own restrictions on baggage names. +For example, the [W3C Baggage specification](https://www.w3.org/TR/baggage/#key) +restricts the baggage keys to strings that satisfy the `token` definition +from [RFC7230, Section 3.2.6](https://tools.ietf.org/html/rfc7230#section-3.2.6). +For maximum compatibility, alpha-numeric names are strongly recommended +to be used as baggage names. + +Baggage **values** are any valid UTF-8 strings. Language API MUST accept +any valid UTF-8 string as baggage **value** in `Set` and return the same +value from `Get`. + +Language API MUST treat both baggage names and values as case sensitive. +See also [W3C Baggage Rationale](https://github.com/w3c/baggage/blob/main/baggage/HTTP_HEADER_FORMAT_RATIONALE.md#case-sensitivity-of-keys). + +Example: + +``` +baggage.Set('a', 'B% 💼'); +baggage.Set('A', 'c'); +baggage.Get('a'); // returns "B% 💼" +baggage.Get('A'); // returns "c" +``` + The Baggage API consists of: - the `Baggage` as a logical container