Small clean up for Propagators.

specification/context/api-propagators.md

@@ -6,12 +6,17 @@ Table of Contents
 </summary>
 
 - [Overview](#overview)
-- [HTTP Text Format](#http-text-format)
+- [Propagator Types](#propagator-types)
+  - [Carrier](#carrier)
+  - [Operations](#operations)
+    - [Inject](#inject)
+    - [Extract](#extract)
+- [HTTPText Propagator](#httptext-propagator)
   - [Fields](#fields)
-  - [Inject](#inject)
+  - [Inject](#inject-1)
     - [Setter argument](#setter)
       - [Set](#set)
-  - [Extract](#extract)
+  - [Extract](#extract-1)
     - [Getter argument](#getter)
       - [Get](#get)
 - [Composite Propagator](#composite-propagator)
@@ -24,34 +29,88 @@ Table of Contents
 Cross-cutting concerns send their state to the next process using
 `Propagator`s, which are defined as objects used to read and write
 context data to and from messages exchanged by the applications.
-Each concern creates a set of `Propagator`s for every supported `Format`.
+Each concern creates a set of `Propagator`s for every supported
+`Propagator` type.
 
-Propagators leverage the `Context` to inject and extract data for each
+`Propagator`s leverage the `Context` to inject and extract data for each
 cross-cutting concern, such as traces and correlation context.
 
+Propagation is usually implemented via library-specific request
+interceptors, where the client-side injects values and the server-side extracts them.
+
 The Propagators API is expected to be leveraged by users writing
 instrumentation libraries.
 
-The Propagators API currently consists of one `Format`:
+## Propagator Types
+
+A `Propagator` type defines the restrictions imposed by a specific transport
+and bound to a data type, in order to propagate in-band context data across process boundaries.
+
+The Propagators API currently defines one `Propagator` type:
+
+- `HTTPTextPropagator` is a type that inject values into and extracts values
+  from carriers as text.
+
+A binary `Propagator` type will be added in the future.
+
+### Carrier
 
-- `HTTPTextFormat` is used to inject values into and extract values from carriers as text that travel
-  in-band across process boundaries.
+A carrier is the medium used by `Propagator`s to read values from and write values to.
+Each specific `Propagator` type defines its expected carrier type, such as a string map
+or a byte array.
 
-A binary `Format` will be added in the future.
+Carriers used at [Inject](#inject) are expected to be mutable.
 
-## HTTP Text Format
+### Operations
+
+`Propagator`s MUST define `Inject` and `Extract` operations, in order to write
+values to and read values from respectively. Each `Propagator` type MUST define the specific carrier type
+and CAN define additional parameters.
+
+#### Inject
+
+Injects the value downstream. For example, as http headers.
+
+Required arguments:
 
-`HTTPTextFormat` is a formatter that injects and extracts a cross-cutting concern
+- A `Context`. The Propagator MUST retrieve the appropriate value from the `Context` first, such as
+`SpanContext`, `CorrelationContext` or another cross-cutting concern context. For languages
+supporting current `Context` state, this argument is OPTIONAL, defaulting to the current `Context`
+instance.
+- The carrier that holds the propagation fields. For example, an outgoing message or http request.
+
+#### Extract
+
+Extracts the value from an incoming request. For example, from the headers of an HTTP request.
+
+If a value can not be parsed from the carrier for a cross-cutting concern,
+the implementation MUST NOT throw an exception. It MUST store a value in the `Context`
+that the implementation can recognize as a null or empty value.
+
+Required arguments:
+
+- A `Context`. For languages supporting current `Context` state this argument is OPTIONAL, defaulting
+to the current `Context` instance.
+- The carrier that holds the propagation fields. For example, an incoming message or http response.
+
+Returns a new `Context` derived from the `Context` passed as argument,
+containing the extracted value, which can be a `SpanContext`,
+`CorrelationContext` or another cross-cutting concern context.
+
+If the extracted value is a `SpanContext`, its `IsRemote` property MUST be set to true.
+
+## HTTPText Propagator
+
+`HTTPTextPropagator` requires the injection and extraction of a cross-cutting concern
 value as text into carriers that travel in-band across process boundaries.
 
 Encoding is expected to conform to the HTTP Header Field semantics. Values are often encoded as
 RPC/HTTP request headers.
 
 The carrier of propagated data on both the client (injector) and server (extractor) side is
-usually an http request. Propagation is usually implemented via library-specific request
-interceptors, where the client-side injects values and the server-side extracts them.
+usually an http request.
 
-`HTTPTextFormat` MUST expose the APIs that injects values into carriers,
+`HTTPTextPropagator` MUST expose the APIs that injects values into carriers,
 and extracts values from carriers.
 
 ### Fields
@@ -68,23 +127,23 @@ The use cases of this are:
 - allow pre-allocation of fields, especially in systems like gRPC Metadata
 - allow a single-pass over an iterator
 
-Returns list of fields that will be used by this formatter.
+Returns list of fields that will be used by the `HttpTextPropagator`.
 
 ### Inject
 
-Injects the value downstream. For example, as http headers.
+Injects the value downstream.
 
 Required arguments:
 
-- A `Context`. The Propagator MUST retrieve the appropriate value from the `Context` first, such as `SpanContext`, `CorrelationContext` or another cross-cutting concern context. For languages supporting current `Context` state, this argument is OPTIONAL, defaulting to the current `Context` instance.
-- the carrier that holds propagation fields. For example, an outgoing message or http request.
-- the `Setter` invoked for each propagation key to add or remove.
+- A `Context`.
+- The carrier that holds propagation fields. For example, an outgoing message or http request.
+- The `Setter` invoked for each propagation key to add or remove.
 
 #### Setter argument
 
-Setter is an argument in `Inject` that sets value into given field.
+Setter is an argument in `Inject` that sets values into given fields.
 
-`Setter` allows a `HTTPTextFormat` to set propagated fields into a carrier.
+`Setter` allows a `HttpTextPropagator` to set propagated fields into a carrier.
 
 `Setter` MUST be stateless and allowed to be saved as a constant to avoid runtime allocations. One of the ways to implement it is `Setter` class with `Set` method as described below.
 
@@ -98,33 +157,25 @@ Required arguments:
 - the key of the field.
 - the value of the field.
 
-The implemenation SHOULD preserve casing (e.g. it should not transform `Content-Type` to `content-type`) if the used protocol is case insensitive, otherwise it MUST preserve casing.
+The implementation SHOULD preserve casing (e.g. it should not transform `Content-Type` to `content-type`) if the used protocol is case insensitive, otherwise it MUST preserve casing.
 
 ### Extract
 
-Extracts the value from an incoming request. For example, from the headers of an HTTP request.
-
-If a value can not be parsed from the carrier for a cross-cutting concern,
-the implementation MUST NOT throw an exception. It MUST store a value in the `Context`
-that the implementation can recognize as a null or empty value.
+Extracts the value from an incoming request.
 
 Required arguments:
 
-- A `Context`. For languages supporting current `Context` state this argument is OPTIONAL, defaulting to the current `Context` instance.
-- the carrier holds propagation fields. For example, an outgoing message or http request.
-- the instance of `Getter` invoked for each propagation key to get.
-
-Returns a new `Context` derived from the `Context` passed as argument,
-containing the extracted value, which can be a `SpanContext`,
-`CorrelationContext` or another cross-cutting concern context.
+- A `Context`.
+- The carrier holds propagation fields. For example, an incoming message or http response.
+- The instance of `Getter` invoked for each propagation key to get.
 
-If the extracted value is a `SpanContext`, its `IsRemote` property MUST be set to true.
+Returns a new `Context` derived from the `Context` passed as argument.
 
 #### Getter argument
 
 Getter is an argument in `Extract` that get value from given field
 
-`Getter` allows a `HttpTextFormat` to read propagated fields from a carrier.
+`Getter` allows a `HttpTextPropagator` to read propagated fields from a carrier.
 
 `Getter` MUST be stateless and allowed to be saved as a constant to avoid runtime allocations. One of the ways to implement it is `Getter` class with `Get` method as described below.
 
@@ -137,7 +188,7 @@ Required arguments:
 - the carrier of propagation fields, such as an HTTP request.
 - the key of the field.
 
-The Get function is responsible for handling case sensitivity. If the getter is intended to work with a HTTP request object, the getter MUST be case insensitive. To improve compatibility with other text-based protocols, text `Format` implementions MUST ensure to always use the canonical casing for their attributes. NOTE: Cannonical casing for HTTP headers is usually title case (e.g. `Content-Type` instead of `content-type`).
+The Get function is responsible for handling case sensitivity. If the getter is intended to work with a HTTP request object, the getter MUST be case insensitive. To improve compatibility with other text-based protocols, `HTTPTextPropagator`s MUST ensure to always use the canonical casing for their attributes. NOTE: Cannonical casing for HTTP headers is usually title case (e.g. `Content-Type` instead of `content-type`).
 
 ## Composite Propagator
 
@@ -148,9 +199,10 @@ single entity.
 The resulting composite `Propagator` will invoke the `Propagators`
 in the order they were specified.
 
-Each composite `Propagator` will be bound to a specific `Format`, such
-as `HttpTextFormat`, as different `Format`s will likely operate on different
+Each composite `Propagator` will implement a specific `Propagator` type, such
+as `HttpTextPropagator`, as different `Propagator` types will likely operate on different
 data types.
+
 There MUST be functions to accomplish the following operations.
 
 - Create a composite propagator
@@ -184,7 +236,7 @@ Required arguments:
 ## Global Propagators
 
 Implementations MAY provide global `Propagator`s for
-each supported `Format`.
+each supported `Propagator` type.
 
 If offered, the global `Propagator`s should default to a composite `Propagator`
 containing W3C Trace Context and Correlation Context `Propagator`s,
@@ -193,13 +245,13 @@ OpenTelemetry implementations.
 
 ### Get Global Propagator
 
-This method MUST exist for each supported `Format`.
+This method MUST exist for each supported `Propagator` type.
 
 Returns a global `Propagator`. This usually will be composite instance.
 
 ### Set Global Propagator
 
-This method MUST exist for each supported `Format`.
+This method MUST exist for each supported `Propagator` type.
 
 Sets the global `Propagator` instance.
 

specification/overview.md

@@ -239,11 +239,12 @@ See the [Context](context/context.md)
 ## Propagators
 
 OpenTelemetry uses `Propagators` to serialize and deserialize cross-cutting concern values
-such as `SpanContext` and `CorrelationContext` into a `Format`. Currently there is one
-type of propagator:
+such as `SpanContext` and `CorrelationContext`. Different `Propagator` types define the restrictions
+imposed by a specific transport and bound to a data type.
 
-- `HTTPTextFormat` which is used to inject and extract a value as text into carriers that travel
-  in-band across process boundaries.
+The Propagators API currently defines one `Propagator` type:
+
+- `HTTPTextPropagator` injects values into and extracts values from carriers as text.
 
 ## Collector