Update the baggage spec to include opaque metadata. (open-telemetry#1066

)

Co-authored-by: Armin Ruech <armin.ruech@dynatrace.com>

CHANGELOG.md

@@ -9,6 +9,8 @@ release.
 
 New:
 
+- Add Metadata for Baggage entries, and clarify W3C Baggage Propagator implementation
+  ([#1066](https://github.com/open-telemetry/opentelemetry-specification/pull/1066))
 - Change Status to be consistent with Link and Event
   ([#1067](https://github.com/open-telemetry/opentelemetry-specification/pull/1067))
 - Clarify env variables in otlp exporter

specification/baggage/api.md

@@ -64,13 +64,16 @@ contains a `Baggage` with the new value.
 
 REQUIRED parameters:
 
-`Name` the name for which to set the value.
+`Name` The name for which to set the value, of type string.
 
-`Value` the value to set.
+`Value` The value to set, of type string.
 
 OPTIONAL parameters:
 
-`Context` the context containing the `Baggage` in which to set the baggage entry.
+`Metadata` Optional metadata associated with the name-value pair. This should be an opaque wrapper
+for a string with no semantic meaning. Left opaque to allow for future functionality.
+
+`Context` The context containing the `Baggage` in which to set the baggage entry.
 
 ### Remove baggage
 
@@ -104,6 +107,18 @@ The API layer MAY include the following `Propagator`s:
 
 * A `TextMapPropagator` implementing the [W3C Baggage Specification](https://w3c.github.io/baggage).
 
+Note: The W3C baggage specification does not currently assign semantic meaning to the optional metadata.
+
+On `extract`, the propagator should store all metadata as a single metadata instance per entry.
+On `inject`, the propagator should append the metadata per the W3C specification format.
+
+Notes:
+
+If the propagator is unable to parse the `baggage` header, `extract` MUST return a Context with no baggage entries in it.
+
+If the `baggage` header is present, but contains no entries, `extract` MUST return a Context with
+no baggage entries in it.
+
 ## Conflict Resolution
 
 If a new name/value pair is added and its name is the same as an existing name, than the new pair MUST take precedence. The value