Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Specify allowed characters for Baggage keys and values #3801

Merged
merged 14 commits into from
Feb 22, 2024
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
yurishkuro marked this conversation as resolved.
Show resolved Hide resolved
([#3801](https://github.com/open-telemetry/opentelemetry-specification/pull/3801))

### Traces

Expand Down
26 changes: 26 additions & 0 deletions specification/baggage/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading