Spans's parent must be passed as Context instead of Span(Context)s.

CHANGELOG.md

@@ -56,6 +56,9 @@ Updates:
   ([#911](https://github.com/open-telemetry/opentelemetry-specification/pull/911))
 - Explicitly specify the SpanContext APIs IsValid and IsRemote as required
   ([#914](https://github.com/open-telemetry/opentelemetry-specification/pull/914))
+- A full `Context` is the only way to specify a parent of a `Span`.
+  `SpanContext` or even `Span` are not allowed anymore.
+  ([#875](https://github.com/open-telemetry/opentelemetry-specification/pull/875))
 
 ## v0.6.0 (07-01-2020)
 

specification/trace/api.md

@@ -19,8 +19,8 @@ Table of Contents
   * [IsRemote](#isremote)
 * [Span](#span)
   * [Span creation](#span-creation)
-    * [Determining the Parent Span from a Context](#determining-the-parent-span-from-a-context)
     * [Add Links](#add-links)
+  * [Effective Span](#effective-span)
   * [Span operations](#span-operations)
     * [Get Context](#get-context)
     * [IsRecording](#isrecording)
@@ -240,8 +240,7 @@ the entire operation and, optionally, one or more sub-spans for its sub-operatio
 - The span name
 - An immutable [`SpanContext`](#spancontext) that uniquely identifies the
   `Span`
-- A parent span in the form of a [`Span`](#span), [`SpanContext`](#spancontext),
-  or null
+- A parent span in the form of a (possibly empty) [`Context`](../context/context.md)
 - A [`SpanKind`](#spankind)
 - A start timestamp
 - An end timestamp
@@ -307,24 +306,20 @@ directly. All `Span`s MUST be created via a `Tracer`.
 
 There MUST NOT be any API for creating a `Span` other than with a [`Tracer`](#tracer).
 
-When creating a new `Span`, the `Tracer` MUST allow the caller to specify the
-new `Span`'s parent in the form of a `Span` or `SpanContext`. The `Tracer`
-SHOULD create each new `Span` as a child of its active `Span`, unless an
-explicit parent is provided or the option to create a span without a parent is
-selected.
-
 `Span` creation MUST NOT set the newly created `Span` as the currently
 active `Span` by default, but this functionality MAY be offered additionally
 as a separate operation.
 
 The API MUST accept the following parameters:
 
 - The span name. This is a required parameter.
-- The parent `Span` or a `Context` containing a parent `Span` or `SpanContext`,
-  and whether the new `Span` should be a root `Span`. API MAY also have an
-  option for implicit parenting from the current context as a default behavior.
-  See [Determining the Parent Span from a Context](#determining-the-parent-span-from-a-context)
-  for guidance on `Span` parenting from explicit and implicit `Context`s.
+- The parent `Context` or an indication that the new `Span` should be a root `Span`.
+  The API MAY also have an option for implicitly using
+  the current Context as parent as a default behavior.
+  This API MUST NOT accept a `Span` or `SpanContext` as parent, only a full `Context`.
+
+  The semantic parent of the Span MUST be determined according to the rules
+  described in the [Effective Span section](#effective-span).
 - [`SpanKind`](#spankind), default to `SpanKind.Internal` if not specified.
 - [`Attributes`](../common/common.md#attributes). Additionally,
   these attributes may be used to make a sampling decision as noted in [sampling
@@ -354,21 +349,6 @@ created in another process. Each propagators' deserialization must set
 `IsRemote` to true on a parent `SpanContext` so `Span` creation knows if the
 parent is remote.
 
-#### Determining the Parent Span from a Context
-
-When a new `Span` is created from a `Context`, the `Context` may contain:
-
-- A current `Span`
-- An extracted `SpanContext`
-- A current `Span` and an extracted `SpanContext`
-- Neither a current `Span` nor an extracted `Span` context
-
-The parent should be selected in the following order of precedence:
-
-- Use the current `Span`, if available.
-- Use the extracted `SpanContext`, if available.
-- There is no parent. Create a root `Span`.
-
 #### Add Links
 
 During the `Span` creation user MUST have the ability to record links to other `Span`s.
@@ -391,6 +371,21 @@ The Span creation API MUST provide:
 
 Links SHOULD preserve the order in which they're set.
 
+### Effective Span
+
+The *effective span* of a [`Context`](../context/context.md) is the first of the
+following that is available in it (with the respective key if applicable):
+
+1. An actual `Span` object.
+2. An extracted `SpanContext`
+   (that MAY be wrapped in an otherwise empty non-recording `Span`).
+3. Nothing (which SHOULD be represented as a non-null empty `SpanContext` or `Span`).
+
+The API MUST provide functionality to get the effective Span from a `Context`.
+
+Given a `Span` with its parent `Context`, the semantic parent Span is the
+effective span in that parent `Context`.
+
 ### Span operations
 
 With the exception of the function to retrieve the `Span`'s `SpanContext` and

specification/trace/sdk.md

@@ -276,19 +276,22 @@ in the SDK:
 
 ### Interface definition
 
-#### OnStart(Span)
+#### OnStart
 
 `OnStart` is called when a span is started. This method is called synchronously
 on the thread that started the span, therefore it should not block or throw
 exceptions.
 
 **Parameters:**
 
-* `Span` - a [read/write span object](#additional-span-interfaces) for the started span.
+* `span` - a [read/write span object](#additional-span-interfaces) for the started span.
   It SHOULD be possible to keep a reference to this span object and updates to the span
   SHOULD be reflected in it.
   For example, this is useful for creating a SpanProcessor that periodically
   evaluates/prints information about all active span from a background thread.
+* `parentContext` - the parent `Context` of the span that the SDK determined
+  (the explicitly passed `Context`, the current `Context` or an empty `Context`
+  if that was explicitly requested).
 
 **Returns:** `Void`